Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 918
| Download | |
| Open PDF In Browser | View PDF |
PLUMED
2.6.0-dev
Generated by Doxygen 1.8.14
Contents
1
2
3
Introduction
1
1.1
About this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
1.2
Codes interfaced with PLUMED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
Change Log
3
2.1
Version 2.0
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
2.2
Version 2.1
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
2.3
Version 2.2
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
2.4
Version 2.3
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
2.5
Version 2.4
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25
2.6
Version 2.5
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
2.7
Unreleased changes
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installation
35
37
3.1
Supported compilers
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
37
3.2
Configuring PLUMED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
38
3.2.1
BLAS and LAPACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40
3.2.2
VMD trajectory plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
41
3.3
Compiling PLUMED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
41
3.4
Installing PLUMED
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
43
3.5
Patching your MD code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
44
3.6
Cross compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
45
3.7
Installing PLUMED with MacPorts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
46
3.8
Installing PLUMED on a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
47
ii
CONTENTS
3.9
4
5
Installing Python wrappers
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
48
3.9.1
Installing Python wrappers within PLUMED
. . . . . . . . . . . . . . . . . . . . . . . . .
48
3.9.2
Installing Python wrappers outside PLUMED . . . . . . . . . . . . . . . . . . . . . . . . .
48
3.10 Other hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
49
3.11 Code specific notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
49
3.11.1 gromacs-2016.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
49
3.11.2 gromacs-2018.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
50
3.11.3 gromacs-4.5.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
50
3.11.4 namd-2.12
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
50
3.11.5 namd-2.13
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51
3.11.6 qespresso-5.0.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51
3.11.7 qespresso-6.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51
Getting Started
53
4.1
Plumed units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
54
4.2
UNITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
54
Collective Variables
57
5.1
Groups and Virtual Atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
58
5.1.1
Specifying Atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
58
5.1.1.1
Molecules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
58
5.1.1.2
Broken Molecules and PBC . . . . . . . . . . . . . . . . . . . . . . . . . . . .
59
5.1.2
Virtual Atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
59
5.1.3
GROUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
60
5.1.4
MOLINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
61
5.1.5
WHOLEMOLECULES
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
64
5.1.6
FIT_TO_TEMPLATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
66
5.1.7
WRAPAROUND
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
68
5.1.8
RESET_CELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
70
5.1.9
CENTER_OF_MULTICOLVAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
71
5.1.10 CENTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
72
Generated by Doxygen
CONTENTS
iii
5.1.11 COM
5.2
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
74
5.1.12 FIXEDATOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
75
5.1.13 GHOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
76
CV Documentation
76
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1
ADAPTIVE_PATH
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
78
5.2.2
ALPHABETA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
79
5.2.3
ALPHARMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
81
5.2.4
ANGLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
84
5.2.5
ANTIBETARMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
85
5.2.6
CELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
87
5.2.7
CONSTANT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
88
5.2.8
CONTACTMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
89
5.2.9
COORDINATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
91
5.2.10 DHENERGY
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
93
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
94
5.2.12 DIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
96
5.2.13 DIPOLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
98
5.2.14 DISTANCE_FROM_CONTOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
99
5.2.11 DIHCOR
5.2.15 DISTANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
5.2.16 EEFSOLV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
5.2.17 ENERGY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
5.2.18 ERMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
5.2.19 EXTRACV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
5.2.20 FAKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
5.2.21 GPROPERTYMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
5.2.22 GYRATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
5.2.23 PARABETARMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
5.2.24 PATHMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
5.2.25 PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.2.26 PCAVARS
Generated by Doxygen
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
iv
CONTENTS
5.2.27 POSITION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
5.2.28 PROPERTYMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
5.2.29 PUCKERING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
5.2.30 TEMPLATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
5.2.31 TORSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
5.2.32 VOLUME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
5.3
5.4
Distances from reference configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.3.1
DRMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.3.2
MULTI_RMSD
5.3.3
PCARMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
5.3.4
RMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
5.3.5
TARGET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
5.4.1
COMBINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
5.4.2
CUSTOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
5.4.2.1
TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
5.4.3
ENSEMBLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
5.4.4
FUNCPATHMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
5.4.5
FUNCSUMHILLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
5.4.6
LOCALENSEMBLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
5.4.7
MATHEVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
5.4.8
PIECEWISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.4.9
SORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
5.4.10 STATS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
5.5
MultiColvar
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
5.5.1
MultiColvar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
5.5.2
MultiColvar bias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
5.5.3
Extracting all the base quantities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
5.5.4
ANGLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
5.5.5
BOND_DIRECTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Generated by Doxygen
CONTENTS
v
5.5.6
BRIDGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
5.5.7
COORDINATIONNUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.5.8
DENSITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
5.5.9
DISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
5.5.10 FCCUBIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
5.5.11 HBPAMM_SH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
5.5.12 INPLANEDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
5.5.13 MOLECULES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
5.5.14 PLANES
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
5.5.15 Q3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
5.5.16 Q4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
5.5.17 Q6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
5.5.18 SIMPLECUBIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
5.5.19 TETRAHEDRAL
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
5.5.20 TORSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
5.5.21 XANGLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
5.5.22 XDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
5.5.23 XYDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
5.5.24 XYTORSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
5.5.25 XZDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
5.5.26 XZTORSIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
5.5.27 YANGLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
5.5.28 YDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
5.5.29 YXTORSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
5.5.30 YZDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
5.5.31 YZTORSIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
5.5.32 ZANGLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
5.5.33 ZDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
5.5.34 ZXTORSIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
5.5.35 ZYTORSIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Generated by Doxygen
vi
CONTENTS
5.5.36 MFILTER_BETWEEN
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
5.5.37 MFILTER_LESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
5.5.38 MFILTER_MORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
5.5.39 AROUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
5.5.40 CAVITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
5.5.41 INCYLINDER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
5.5.42 INENVELOPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
5.5.43 INSPHERE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
5.5.44 TETRAHEDRALPORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
5.5.45 GRADIENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
5.5.46 INTERMOLECULARTORSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
5.5.47 LOCAL_AVERAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
5.5.48 LOCAL_Q3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
5.5.49 LOCAL_Q4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
5.5.50 LOCAL_Q6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
5.5.51 MCOLV_COMBINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
5.5.52 MCOLV_PRODUCT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
5.5.53 NLINKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
5.5.54 PAMM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
5.5.55 POLYMER_ANGLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
5.5.56 SMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
5.5.57 MTRANSFORM_BETWEEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
5.5.58 MTRANSFORM_LESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
5.5.59 MTRANSFORM_MORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
5.5.60 LWALLS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
5.5.61 UWALLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
5.6
Exploiting contact matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
5.6.1
ALIGNED_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
5.6.2
CONTACT_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
5.6.3
HBOND_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Generated by Doxygen
CONTENTS
vii
5.6.4
HBPAMM_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
5.6.5
SMAC_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
5.6.6
TOPOLOGY_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
5.6.7
CLUSTER_WITHSURFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
5.6.8
COLUMNSUMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
5.6.9
DFSCLUSTERING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
5.6.10 ROWSUMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
5.6.11 SPRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
5.6.12 CLUSTER_DIAMETER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
5.6.13 CLUSTER_DISTRIBUTION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
5.6.14 CLUSTER_NATOMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
5.6.15 CLUSTER_PROPERTIES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
5.6.16 DUMPGRAPH
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
5.6.17 OUTPUT_CLUSTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
6
Analysis
357
6.1
Reweighting and Averaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
6.2
Diagnostic tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
6.3
Storing data for analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
6.4
Calculating dissimilarity matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
6.5
Landmark Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
6.6
Dimensionality Reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
6.7
Outputting the results from analysis algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
6.8
COMMITTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
6.9
DUMPATOMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
6.10 DUMPDERIVATIVES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
6.11 DUMPFORCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
6.12 DUMPMASSCHARGE
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
6.13 DUMPMULTICOLVAR
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
6.14 DUMPPROJECTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
6.15 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Generated by Doxygen
viii
CONTENTS
6.15.1 FLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
6.16 UPDATE_IF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
6.17 REWEIGHT_BIAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
6.18 REWEIGHT_METAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
6.19 REWEIGHT_TEMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
6.20 REWEIGHT_WHAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
6.21 WHAM_HISTOGRAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
6.22 WHAM_WEIGHTS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
6.23 AVERAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
6.24 HISTOGRAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
6.25 MULTICOLVARDENS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
6.26 CONVERT_TO_FES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
6.27 DUMPCUBE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
6.28 DUMPGRID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
6.29 FIND_CONTOUR_SURFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
6.30 FIND_CONTOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
6.31 FIND_SPHERICAL_CONTOUR
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
6.32 FOURIER_TRANSFORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
6.33 GRID_TO_XYZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
6.34 INTEGRATE_GRID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
6.35 INTERPOLATE_GRID
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
6.36 COLLECT_FRAMES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
6.37 EUCLIDEAN_DISSIMILARITIES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
6.38 PRINT_DISSIMILARITY_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
6.39 READ_DISSIMILARITY_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
6.40 LANDMARK_SELECT_FPS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
6.41 LANDMARK_SELECT_RANDOM
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
6.42 LANDMARK_SELECT_STAGED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
6.43 LANDMARK_SELECT_STRIDE
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
6.44 RESELECT_LANDMARKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
6.45 CLASSICAL_MDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
6.45.1 Method of optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
6.46 OUTPUT_PCA_PROJECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
6.47 PCA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
6.48 PROJECT_ALL_ANALYSIS_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
6.49 SKETCHMAP_CONJGRAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
6.50 SKETCHMAP_POINTWISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
6.51 SKETCHMAP_READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
6.52 SKETCHMAP_SMACOF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
6.53 SKETCH_MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
6.54 SMACOF_MDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
6.55 OUTPUT_ANALYSIS_DATA_TO_COLVAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
6.56 OUTPUT_ANALYSIS_DATA_TO_PDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Generated by Doxygen
CONTENTS
7
ix
Bias
429
7.1
ABMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
7.2
BIASVALUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
7.3
EXTENDED_LAGRANGIAN
7.4
EXTERNAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
7.5
LOWER_WALLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
7.6
MAXENT
7.7
METAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
7.8
MOVINGRESTRAINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
7.9
PBMETAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
7.10 RESTRAINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
7.11 UPPER_WALLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
7.12 RESTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
8
Additional Modules
8.1
459
PLUMED-ISDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
8.1.1
8.1.2
CVs Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
8.1.1.1
CS2BACKBONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
8.1.1.2
EMMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
8.1.1.3
FRET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
8.1.1.4
JCOUPLING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
8.1.1.5
NOE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
8.1.1.6
PCS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
8.1.1.7
PRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
8.1.1.8
RDC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
8.1.1.9
SAXS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
Functions Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
8.1.2.1
8.1.3
Generated by Doxygen
SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Biases Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
8.1.3.1
CALIBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
8.1.3.2
METAINFERENCE
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
x
CONTENTS
8.1.3.3
8.2
8.1.4
SELECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
8.1.5
Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
8.1.5.1
ISDB: setting up a Metadynamics Metainference simulation . . . . . . . . . . . 496
8.1.5.2
ISDB: setting up a SAXS post processing and refinement calculation using MA←RTINI form factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
Logarithmic Mean Force Dynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
8.2.1
Biases Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
8.2.1.1
8.3
Loss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
8.3.1.1
8.3.2
8.3.3
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
8.3.2.1
MAZE_MEMETIC_SAMPLING . . . . . . . . . . . . . . . . . . . . . . . . . . 515
8.3.2.2
MAZE_RANDOM_ACCELERATION_MD . . . . . . . . . . . . . . . . . . . . . 517
8.3.2.3
MAZE_RANDOM_WALK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
8.3.2.4
MAZE_SIMULATED_ANNEALING . . . . . . . . . . . . . . . . . . . . . . . . 520
8.3.2.5
MAZE_STEERED_MD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
Biases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
MAZE_OPTIMIZER_BIAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
Experiment Directed Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
8.4.1
Biases Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
8.4.1.1
EDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Extended-System Adaptive Biasing Force . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
8.5.1
Biases Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
8.5.1.1
8.5.2
DRR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Command Line Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
8.5.2.1
8.6
MAZE_LOSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
Optimizers
8.3.3.1
8.5
LOGMFD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
MAZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
8.3.1
8.4
RESCALE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
drr_tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Variationally Enhanced Sampling (VES code)
8.6.1
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Biases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
8.6.1.1
VES_DELTA_F
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Generated by Doxygen
CONTENTS
xi
8.6.1.2
8.6.2
VES_LINEAR_EXPANSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
Basis functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
8.6.2.1
BF_CHEBYSHEV_RATIONAL_FULL_INFINITE . . . . . . . . . . . . . . . . . 543
8.6.2.2
BF_CHEBYSHEV_RATIONAL_SEMI_INFINITE . . . . . . . . . . . . . . . . . 544
8.6.2.3
BF_CHEBYSHEV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
8.6.2.4
BF_COMBINED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
8.6.2.5
BF_COSINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
8.6.2.6
BF_CUBIC_B_SPLINES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
8.6.2.7
BF_CUSTOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
8.6.2.8
BF_FOURIER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
8.6.2.9
BF_HERMITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
8.6.2.10 BF_LAGUERRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
8.6.2.11 BF_LEGENDRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
8.6.2.12 BF_POWERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
8.6.2.13 BF_SINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
8.6.3
Target Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
8.6.3.1
TD_CHISQUARED
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
8.6.3.2
TD_CHI
8.6.3.3
TD_CUSTOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
8.6.3.4
TD_EXPONENTIALLY_MODIFIED_GAUSSIAN . . . . . . . . . . . . . . . . . 560
8.6.3.5
TD_EXPONENTIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
8.6.3.6
TD_GAUSSIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
8.6.3.7
TD_GENERALIZED_EXTREME_VALUE . . . . . . . . . . . . . . . . . . . . . 565
8.6.3.8
TD_GENERALIZED_NORMAL . . . . . . . . . . . . . . . . . . . . . . . . . . 566
8.6.3.9
TD_GRID
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
8.6.3.10 TD_LINEAR_COMBINATION . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
8.6.3.11 TD_MARGINAL_WELLTEMPERED . . . . . . . . . . . . . . . . . . . . . . . . 570
8.6.3.12 TD_PRODUCT_COMBINATION
. . . . . . . . . . . . . . . . . . . . . . . . . 571
8.6.3.13 TD_PRODUCT_DISTRIBUTION
. . . . . . . . . . . . . . . . . . . . . . . . . 572
8.6.3.14 TD_UNIFORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
Generated by Doxygen
xii
CONTENTS
8.6.3.15 TD_VONMISES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
8.6.3.16 TD_WELLTEMPERED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
8.6.4
8.6.5
8.6.6
Optimizers
8.6.4.1
OPT_AVERAGED_SGD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
8.6.4.2
OPT_DUMMY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582
8.6.4.3
OPT_ROBBINS_MONRO_SGD . . . . . . . . . . . . . . . . . . . . . . . . . . 584
8.6.4.4
OPT_STEEPEST_DECENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586
Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587
8.6.5.1
VES_OUTPUT_BASISFUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . 587
8.6.5.2
VES_OUTPUT_FES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
8.6.5.3
VES_OUTPUT_TARGET_DISTRIBUTION . . . . . . . . . . . . . . . . . . . . 590
Command Line Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
8.6.6.1
8.6.7
8.7
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
ves_md_linearexpansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593
8.6.7.1
MARVEL-VES School February 2017 . . . . . . . . . . . . . . . . . . . . . . . 594
8.6.7.2
MARVEL-VES tutorial (Lugano Feb 2017): Metadynamics . . . . . . . . . . . . 595
8.6.7.3
MARVEL-VES tutorial (Lugano Feb 2017): VES 1
. . . . . . . . . . . . . . . . 601
8.6.7.4
MARVEL-VES tutorial (Lugano Feb 2017): VES 2
. . . . . . . . . . . . . . . . 607
8.6.7.5
MARVEL-VES tutorial (Lugano Feb 2017): Kinetics . . . . . . . . . . . . . . . . 611
PIV collective variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
8.7.1
CVs Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
8.7.1.1
PIV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
Generated by Doxygen
CONTENTS
xiii
9
621
Command Line Tools
9.1
completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
9.2
config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
9.3
driver-float . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
9.4
driver
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
9.4.1
READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626
9.5
gentemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
9.6
info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
9.7
kt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
9.8
manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
9.9
mklib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
9.10 newcv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
9.11 partial_tempering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
9.12 patch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
9.13 pathtools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
9.14 pdbrenumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
9.15 pesmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
9.16 simplemd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
9.17 sum_hills
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
9.18 vim2html . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
Generated by Doxygen
xiv
CONTENTS
10 Miscelaneous
643
10.1 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
10.1.1 ENDPLUMED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
10.2 Continuation lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
10.3 Using VIM syntax file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
10.4 Using bash autocompletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
10.5 Including other files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
10.5.1 INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
10.6 Loading shared libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
10.6.1 LOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
10.7 Embed a separate PLUMED instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
10.7.1 PLUMED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
10.8 Debugging the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
10.8.1 DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
10.9 Changing exchange patterns in replica exchange
. . . . . . . . . . . . . . . . . . . . . . . . . . 659
10.9.1 RANDOM_EXCHANGES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
10.10List of modules
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
10.11Special replica syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
10.12Parsing constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
10.13Frequently used tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
10.13.1 histogrambead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664
10.13.2 kernelfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664
10.13.3 pdbreader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
10.13.4 switchingfunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
10.13.5 Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
10.13.6 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
10.13.6.1 Restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
10.13.6.2 Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
10.13.6.3 Replica suffix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
Generated by Doxygen
CONTENTS
xv
11 Tutorials
673
11.1 Trieste tutorial: Analyzing trajectories using PLUMED . . . . . . . . . . . . . . . . . . . . . . . . 674
11.1.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
11.1.2 Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
11.1.3 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
11.1.4 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
11.1.5 Using PLUMED from the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
11.1.6 The structure of a PLUMED input file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
11.1.6.1 Exercise 1: Computing and printing collective variables . . . . . . . . . . . . . . 677
11.1.6.2 Exercise 1b: Combining collective variables . . . . . . . . . . . . . . . . . . . . 679
11.1.7 Solving periodic-boundary conditions issues . . . . . . . . . . . . . . . . . . . . . . . . . 680
11.1.7.1 Exercise 2: Solving PBC issues and dump atomic coordinates . . . . . . . . . . 681
11.1.7.2 Exercise 2b: Mistakes with WHOLEMOLECULES
. . . . . . . . . . . . . . . . 682
11.1.7.3 Exercise 2c: Mastering FIT_TO_TEMPLATE . . . . . . . . . . . . . . . . . . . 683
11.1.7.4 Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
11.2 Trieste tutorial: Averaging, histograms and block analysis . . . . . . . . . . . . . . . . . . . . . . 684
11.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
11.2.2 Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
11.2.3 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
11.2.4 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686
11.2.4.1 Calculating an ensemble average . . . . . . . . . . . . . . . . . . . . . . . . . 686
11.2.4.2 Calculating a histogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
11.2.4.3 Problem I: Making the best use of the data . . . . . . . . . . . . . . . . . . . . 688
11.2.4.4 Problem II: Dealing with rare events and simulation biases . . . . . . . . . . . . 689
11.2.4.5 Problem III: Dealing with correlated variables . . . . . . . . . . . . . . . . . . . 692
11.2.4.6 Putting it all together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
11.2.5 Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
11.3 Trieste tutorial: Using restraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
11.3.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
11.3.2 Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
Generated by Doxygen
xvi
CONTENTS
11.3.3 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
11.3.4 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
11.3.4.1 Biased sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
11.3.5 Exercise 1: converged histogram of the water dimer relative distance . . . . . . . . . . . . 699
11.3.6 Exercise 2: Apply a linear restraint on the same collective variable . . . . . . . . . . . . . 699
11.3.7 Exercise 3: Apply a quadratic restraint on the same collective variable . . . . . . . . . . . 701
11.3.8 Exercise 4: Apply an upper wall on the distance. . . . . . . . . . . . . . . . . . . . . . . . 701
11.3.9 Exercise 5: Evaluate the free energy and use it as an external restraint . . . . . . . . . . . 702
11.3.10 Exercise 6: Preliminary run with Alanine dipeptide . . . . . . . . . . . . . . . . . . . . . . 703
11.3.11 Exercise 7: First biased run with Alanine dipeptide . . . . . . . . . . . . . . . . . . . . . . 704
11.3.12 Exercise 8: Second biased run with Alanine dipeptide . . . . . . . . . . . . . . . . . . . . 704
11.4 Trieste tutorial: Metadynamics simulations with PLUMED . . . . . . . . . . . . . . . . . . . . . . 705
11.4.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
11.4.2 Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
11.4.3 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
11.4.4 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
11.4.5 Exercise 1: my first metadynamics calculation . . . . . . . . . . . . . . . . . . . . . . . . 707
11.4.5.1 Exercise 1a: setup and run
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
11.4.5.2 Exercise 1b: estimating the free energy . . . . . . . . . . . . . . . . . . . . . . 709
11.4.6 Exercise 2: playing with collective variables . . . . . . . . . . . . . . . . . . . . . . . . . 710
11.4.7 Exercise 3: estimating the error in free-energies using block-analysis . . . . . . . . . . . . 710
11.4.8 Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
11.5 Trieste tutorial: Running and analyzing multi-replica simulations. . . . . . . . . . . . . . . . . . . . 713
11.5.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
11.5.2 Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
11.5.3 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
11.5.4 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
11.5.5 Multi replica input files
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
11.5.6 Using special syntax for multiple replicas . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
11.5.7 Exercise 1: Running multi-replica simulations . . . . . . . . . . . . . . . . . . . . . . . . 716
Generated by Doxygen
CONTENTS
xvii
11.5.8 Exercise 2: Analyzing a multiple-restraint simulation . . . . . . . . . . . . . . . . . . . . . 717
11.5.9 Exercise 3: What if a variable is missing? . . . . . . . . . . . . . . . . . . . . . . . . . . 720
11.5.10 Exercise 4: "demuxing" your trajectories . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
11.5.11 Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
11.6 Trieste tutorial: Real-life applications with complex CVs . . . . . . . . . . . . . . . . . . . . . . . 721
11.6.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
11.6.2 Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
11.6.3 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
11.6.4 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
11.6.5 Exercise 1: analysis of the BARD1 complex simulation
. . . . . . . . . . . . . . . . . . . 722
11.6.6 Exercise 2: analysis of the cmyc-urea simulation . . . . . . . . . . . . . . . . . . . . . . . 723
11.6.7 Exercise 3: Protein G folding simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
11.6.8 Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
11.7 Belfast tutorial: Analyzing CVs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
11.7.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
11.7.2 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
11.7.3 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
11.7.4 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
11.7.4.1 A note on units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
11.7.4.2 Introduction to the PLUMED input file . . . . . . . . . . . . . . . . . . . . . . . 726
11.7.4.3 MULTICOLVAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
11.7.4.4 Analysis of Collective Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 729
11.8 Belfast tutorial: Adaptive variables I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
11.8.1 Aim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
11.8.2 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
11.8.3 What happens when in a complex reaction? . . . . . . . . . . . . . . . . . . . . . . . . . 730
11.8.4 Path collective variables
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
11.8.5 A note on the path topology
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
11.8.6 How many frames do I need? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734
11.8.7 Some tricks of the trade: the neighbors list.
Generated by Doxygen
. . . . . . . . . . . . . . . . . . . . . . . . . 734
xviii
CONTENTS
11.8.8 The molecule of the day: alanine dipeptide . . . . . . . . . . . . . . . . . . . . . . . . . . 734
11.8.9 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
11.8.10 How to format my input? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
11.8.11 Fast forward: metadynamics on the path . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
11.9 Belfast tutorial: Adaptive variables II
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
11.9.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
11.9.2 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
11.9.3 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
11.9.4 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
11.9.4.1 Visualizing the trajectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
11.9.4.2 Installing GISMO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
11.9.4.3 Finding collective variables
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
11.9.4.4 Dimensionality reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
11.9.5 Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
11.9.6 Further Reading
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
11.10Belfast tutorial: Umbrella sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
11.10.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
11.10.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
11.10.2.1 Biased sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
11.10.2.2 Umbrella sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744
11.10.2.3 Weighted histogram analysis method . . . . . . . . . . . . . . . . . . . . . . . 745
11.10.3 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
11.10.4 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
11.10.5 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
11.10.5.1 The model system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
11.10.5.2 Restrained simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
11.10.5.3 Reweighting the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
11.10.5.4 A free-energy landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
11.10.5.5 Combining multiple restraints . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
11.10.6 Comments
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
Generated by Doxygen
CONTENTS
xix
11.10.6.1 How does PLUMED work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
11.10.7 Further Reading
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
11.11Belfast tutorial: Out of equilibrium dynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
11.11.1 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
11.11.2 Steered MD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
11.11.3 Moving on a more complex path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
11.11.4 Why work is important? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
11.11.5 Targeted MD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
11.12Belfast tutorial: Metadynamics
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
11.12.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
11.12.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
11.12.3 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
11.12.4 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
11.12.5 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
11.12.5.1 The model system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
11.12.5.2 Exercise 1. Setup and run a metadynamics simulation . . . . . . . . . . . . . . 757
11.12.5.3 Exercise 2. Restart a metadynamics simulation . . . . . . . . . . . . . . . . . . 759
11.12.5.4 Exercise 3. Calculate free-energies and monitor convergence . . . . . . . . . . 759
11.12.5.5 Exercise 4. Setup and run a well-tempered metadynamics simulation, part I . . . 761
11.12.5.6 Exercise 5. Setup and run a well-tempered metadynamics simulation, part II
. . 762
11.13Belfast tutorial: Replica exchange I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
11.13.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
11.13.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
11.13.3 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
11.13.4 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
11.13.5 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
11.13.5.1 The model system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764
11.13.5.2 Exercise 1. Setup and run a PT simulation, part I . . . . . . . . . . . . . . . . . 764
11.13.5.3 Exercise 2. Setup and run a PT simulation, part II
. . . . . . . . . . . . . . . . 766
11.13.5.4 Exercise 3. Setup and run a PTMetaD simulation . . . . . . . . . . . . . . . . . 767
Generated by Doxygen
xx
CONTENTS
11.13.5.5 Exercise 4. The Well-Tempered Ensemble . . . . . . . . . . . . . . . . . . . . 768
11.14Belfast tutorial: Replica exchange II and Multiple walkers
. . . . . . . . . . . . . . . . . . . . . . 770
11.14.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
11.14.1.1 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
11.14.2 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
11.14.3 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
11.14.3.1 Bias-Exchange Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
11.14.3.2 Convergence of the Simulations . . . . . . . . . . . . . . . . . . . . . . . . . . 772
11.14.3.3 Bias-Exchange Analysis with METAGUI . . . . . . . . . . . . . . . . . . . . . . 772
11.14.3.4 Multiple Walker Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
11.14.4 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
11.15Belfast tutorial: NMR restraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
11.15.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
11.15.1.1 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
11.15.2 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
11.15.3 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
11.15.3.1 Experimental data as Collective Variables . . . . . . . . . . . . . . . . . . . . . 776
11.15.3.2 Replica-Averaged Restrained Simulations . . . . . . . . . . . . . . . . . . . . . 777
11.15.4 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
11.16Belfast tutorial: Steinhardt Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
11.16.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
11.16.1.1 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
11.16.2 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
11.16.3 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
11.16.3.1 Simplemd
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
11.16.3.2 Coordination Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
11.16.3.3 Steinhardt parameter
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
11.16.3.4 Local versus Global . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781
11.16.3.5 Local Steinhardt parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781
11.16.4 Further Reading
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
Generated by Doxygen
CONTENTS
xxi
11.17Cambridge tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
11.17.1 Alanine dipeptide: our toy model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
11.17.2 Exercise 1. Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
11.17.2.1 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
11.17.2.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783
11.17.2.3 Setup, run, and analyze a well-tempered metadynamics simulation
11.17.2.4 Calculate free-energies and monitor convergence
. . . . . . . 784
. . . . . . . . . . . . . . . . 785
11.17.3 Exercise 2. Bias-Exchange Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . 786
11.17.3.1 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
11.17.3.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
11.17.3.3 Setup, run, and analyze a well-tempered bias-exchange metadynamics simulation 786
11.17.3.4 Calculate free-energies and monitor convergence
. . . . . . . . . . . . . . . . 788
11.17.4 Exercise 3. Replica-Average Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . 789
11.17.4.1 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
11.17.4.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
11.17.4.3 The system: Chignolin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
11.17.4.4 Setup, run and analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
11.18CINECA tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
11.18.1 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
11.18.2 Alanine dipeptide: our toy model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
11.18.3 Monitoring collective variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
11.18.3.1 Exercise 1: on-the-fly analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
11.18.3.2 Exercise 2: analysis with the driver tool . . . . . . . . . . . . . . . . . . . . . . 793
11.18.4 Biasing collective variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
11.18.4.1 Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794
11.18.4.2 Restraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
11.18.4.3 Using multiple replicas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
11.18.4.4 Using multiple restraints with replica exchange . . . . . . . . . . . . . . . . . . 801
11.19Using Hamiltonian replica exchange with GROMACS . . . . . . . . . . . . . . . . . . . . . . . . 804
11.19.1 Generate scaled topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804
Generated by Doxygen
xxii
CONTENTS
11.19.2 Run GROMACS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
11.20Julich tutorial: Developing CVs in plumed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
11.20.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
11.20.2 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
11.20.3 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
11.20.4 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
11.20.5 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
11.20.5.1 Calculating a reasonably complex collective variable . . . . . . . . . . . . . . . 808
11.20.5.2 Implementing a new collective variable . . . . . . . . . . . . . . . . . . . . . . 809
11.20.6 Final thoughts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
11.21Lugano tutorial: Analyzing CVs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
11.21.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
11.21.2 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
11.21.3 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
11.21.4 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811
11.21.4.1 PLUMED2's internal units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812
11.21.4.2 Introduction to the PLUMED input file . . . . . . . . . . . . . . . . . . . . . . . 812
11.21.4.3 The PLUMED input syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
11.21.4.4 Center of mass positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
11.21.4.5 Calculating torsion angles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
11.21.4.6 An exercise with the radius of gyration . . . . . . . . . . . . . . . . . . . . . . . 816
11.21.4.7 Coordination numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816
11.21.4.8 Multicolvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817
11.21.4.9 Understanding the need for ensemble averages
. . . . . . . . . . . . . . . . . 818
11.21.4.10Calculating ensemble averages using PLUMED . . . . . . . . . . . . . . . . . . 820
11.21.4.11Calculating histograms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
11.21.4.12A histogram for the protein trajectory . . . . . . . . . . . . . . . . . . . . . . . 822
11.21.5 Conclusions and further work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
11.22Lugano tutorial: Path CVs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
11.22.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
Generated by Doxygen
CONTENTS
xxiii
11.22.2 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823
11.22.3 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
11.22.4 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
11.22.4.1 PCA coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824
11.22.4.2 PCA with the RMSD metric . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
11.22.4.3 The isocommittor surface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
11.22.4.4 Path collective variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828
11.22.4.5 The mathematics of path collective variables . . . . . . . . . . . . . . . . . . . 829
11.22.4.6 The Z(X) collective variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829
11.22.4.7 Optimizing path collective variables . . . . . . . . . . . . . . . . . . . . . . . . 830
11.22.5 Conclusions and further work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
11.23ESDW Workshop Lyon 2019: A very simple introduction to PLUMED . . . . . . . . . . . . . . . . 831
11.23.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
11.23.2 Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
11.23.3 Resources
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
11.23.4 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
11.23.5 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833
11.23.5.1 Using PLUMED as an MD code . . . . . . . . . . . . . . . . . . . . . . . . . . 833
11.23.5.2 Using PLUMED to specify a force field
11.23.5.3 Calculating collective variables
. . . . . . . . . . . . . . . . . . . . . . 834
. . . . . . . . . . . . . . . . . . . . . . . . . . 835
11.23.5.4 Estimating the free energy surface
. . . . . . . . . . . . . . . . . . . . . . . . 836
11.23.5.5 Performing metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
11.23.6 Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
11.24Moving from PLUMED 1 to PLUMED 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
11.24.1 New syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
11.24.2 Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839
11.24.3 Names in output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839
11.24.4 Units
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
11.24.5 Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
11.25Munster tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841
Generated by Doxygen
xxiv
CONTENTS
11.25.1 Alanine dipeptide: our toy model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842
11.25.2 Monitoring collective variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842
11.25.2.1 Analyze on the fly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843
11.25.2.2 Analyze using the driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844
11.25.2.3 Periodic boundaries and explicit water . . . . . . . . . . . . . . . . . . . . . . . 845
11.25.2.4 Other analysis tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845
11.25.3 Biasing collective variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846
11.25.3.1 Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846
11.25.3.2 Restraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
11.25.3.3 Moving restraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
11.25.3.4 Using multiple replicas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853
11.25.3.5 Using multiple restraints with replica exchange . . . . . . . . . . . . . . . . . . 854
11.26Optimizing PLUMED performance
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857
11.26.1 How to optimize a simulation performed with PLUMED . . . . . . . . . . . . . . . . . . . 857
11.26.1.1 Run a simulation with GROMACS alone . . . . . . . . . . . . . . . . . . . . . . 857
11.26.1.2 Run a simulation with GROMACS+PLUMED . . . . . . . . . . . . . . . . . . . 858
11.26.1.3 Timing individual variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858
11.26.1.4 Optimizing coordination numbers using neighbor lists . . . . . . . . . . . . . . . 859
11.26.1.5 Biasing your CVs: multiple time stepping . . . . . . . . . . . . . . . . . . . . . 860
11.26.1.6 Using grids in metadynamics
. . . . . . . . . . . . . . . . . . . . . . . . . . . 860
11.26.1.7 Running GROMACS on the GPU . . . . . . . . . . . . . . . . . . . . . . . . . 862
12 Performances
863
12.1 GROMACS and PLUMED with GPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
12.2 Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
12.3 Multiple time stepping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
12.3.1 EFFECTIVE_ENERGY_DRIFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
12.4 Multicolvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
12.5 Neighbor Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
12.6 OpenMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
12.7 Secondary Structure
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
12.8 Time your Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
12.9 Making lepton library faster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
13 Index of Actions
869
13.1 Full list of actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
14 Todo List
883
15 Bug List
885
Bibliography
892
Generated by Doxygen
Chapter 1
Introduction
PLUMED is a plugin that works with a large number of molecular dynamics codes (Codes interfaced with PLUMED
). It can be used to analyze features of the dynamics on-the-fly or to perform a wide variety of free energy methods.
PLUMED can also work as a Command Line Tools to perform analysis on trajectories saved in most of the existing
formats. If PLUMED is useful for your work please read and cite [1], if you are interested in the PLUMED 1 original
publication please read and cite [2] .
To follow the development of PLUMED 2, you can look at the detailed Change Log .
To install PLUMED, see this page: Installation , while in Getting Started you can find a brief introduction on how to
write your first PLUMED input file.
Tutorials are available to introduce basic as well as more advanced features of PLUMED.
1.1
About this manual
This manual has been compiled from PLUMED version 2.6.0-dev (git version: 5ef1d96 ). Manual built on Travis CI
for branch master-ves.
Regtest results for this version can be found here.
This is the user manual - if you want to modify PLUMED or to understand how it works internally, have a look at the
developer manual .
1.2
Codes interfaced with PLUMED
PLUMED can be incorporated into an MD code and used to analyze or bias a molecular dynamics run on the fly.
Some MD code could already include calls to the PLUMED library and be PLUMED-ready in its original distribution.
As far as we know, the following MD codes can be used with PLUMED out of the box:
• AmberTools, sander module, since version 15.
• CP2K, since Feb 2015.
• ESPResSo, in a version that has been patched with PLUMED can be found here.
• PINY-MD, in its plumed branch.
2
Introduction
• IPHIGENIE.
• AceMD, see this link.
• OpenMM, using the openmmp-plumed plugin.
• DL_POLY4.
• VNL-ATK, see this link.
• ABIN.
• i-pi.
• LAMMPS since Nov 2018.
Please refer to the documentation of the MD code to know how to use it with the latest PLUMED release. If you
maintain another MD code that is PLUMED-ready let us know and we will add it to this list.
Additionally, we provide patching procedures for the following codes:
• gromacs-2016-6
• gromacs-2018-6
• gromacs-4-5-7
• namd-2-12
• namd-2-13
• qespresso-5-0-2
• qespresso-6-2
Alternatively, one can use PLUMED as a Command Line Tools for post processing the results from molecular dynamics or enhanced sampling calculations. Notice that PLUMED can be used as an analysis tool also from the
following packages:
• PLUMED-GUI is a VMD plugin that computes PLUMED collective variables.
• HTMD can use PLUMED collective variables for analysis.
• OpenPathSampling, using the PLUMED Wrapper for OpenPathSampling.
Generated by Doxygen
Chapter 2
Change Log
Here you can find a history of changes across different PLUMED versions. The future releases are expected to
follow more or less the pace of the old release. This means:
• Approximately once per year, after summer, a new release (2.X). These releases typically group together all
the features that were contributed during the year.
• Approximately every three month, we announce a patch (e.g. 2.2.X). This typically contains bug fixes, and
could occasionally contain a new feature.
A few months before each new release we provide a beta release. We typically maintain release branches until the
fifth patch release (2.X.5), which should come out approximately 15 month after the original release (2.X). After that,
branches are not supported anymore.
Notice that occasionally we publish patches on the mailing list. These patches are always included in the following
release, but we encourage users that want to be up to date to follow the mailing list.
Below you can find change logs for all the published releases. We mostly add new features without breaking existing
ones. However, some of the changes lead to incompatible behavior. In the Change Log we try to give as much
visibility as possible to these changes to avoid surprises.
We also log changes that are relevant if you are developing the code. These change lists are however not complete,
and if you want to put your hands in the code and maintain your own collective variables we suggest you to follow
the development on github.
• Changes for Version 2.0
• Changes for Version 2.1
• Changes for Version 2.2
• Changes for Version 2.3
• Changes for Version 2.4
• Changes for Version 2.5
• Changes for Unreleased changes
4
2.1
Change Log
Version 2.0
Version 2.0.0 (Sep 27, 2013)
Version 2.0 is a complete rewrite, so there is no way to write a complete set of difference with respect to plumed
1.3. Here is a possibly incomplete summary of the difference:
• The input is simpler, more flexible, and more error proof. Many checks are now performed and in this way
common errors are avoided.
• The units are now the same for all MD codes. If you want to use a different unit than the default you set it in
the input file.
• The analysis tools are now much more flexible. As an example of this it is now possible to write different
collective variables with different frequencies.
• Many complex collective variables are considerably faster than they were in plumed1. In particular, all variables based on RMSD distances.
• Centers of mass can be used as if they were atoms. Hence, unlike plumed 1.3, you can use center of mass
positions in ALL collective variables.
• The virial contribution is now computed and passed to the MD code. Plumed can thus now be used to perform
biased NPT simulations.
• Variables can be dumped on different files, and are computed only when this is necessary.
• PLUMED is now compiled as a separate library. This simplifies the patching procedure, but might require
some extra work to configure PLUMED properly. Since PLUMED can be loaded as a shared library, it is
possible to setup everything such that PLUMED and MD codes can be updated independently from each
other.
In addition, it is now much easier to contribute new functionality to the code because:
• There is a much simpler interface between plumed and the base MD codes. This makes it much easier to
add plumed to a new MD code. Hopefully, in the future, interfaces with MD codes will be maintained by the
developers of the MD codes independently from PLUMED developers. This will allow more MD codes to be
compatible with PLUMED.
• There is C++ object oriented programming and full compatibility with the C++ standard library
• A modular structure.
• New collective variables and methods can be released independently.
• There is an extensive developer documentation.
• User documentation is provided together inside the implementation files.
Caveats:
• PLUMED 2 input file (plumed.dat) has a syntax which is not compatible with PLUMED 1. Transition should
be easy, but cannot be done just using the new version with the old input file.
• PLUMED 2 is written in C++, thus requires a C++ compiler
• PLUMED 2 may not include all the features that were available in PLUMED 1.
A tutorial explaining how to move from PLUMED 1 to PLUMED 2 is available (see Moving from PLUMED 1 to PLUMED 2).
Generated by Doxygen
2.1 Version 2.0
5
Version 2.0.1 (Nov 14, 2013)
For users:
• Fixed a bug in HISTOGRAM with REWEIGHT_BIAS. Reweighting was only done when also temperaturereweighting was enabled.
• Fixed a bug that was sometime crashing code with domain decomposition and non-dense simulation boxes
(e.g. implicit solvent).
• Performance improvements for GYRATION.
• Flush all files every 10000 steps by default, without need to use FLUSH
• Errors when writing input for switchingfunction are now properly recognized.
• Added message when simplemd is used on a non-existing file.
• Fixed plumed mklib such that it deletes the target shared library in case of compilation error.
• Several small fixes in documentation and log file.
For developers:
• Added possibility to setup replica exchange from MD codes in Fortran (commands "GREX setMPIF←Intercomm" and "GREX setMPIFIntracomm").
• cmd("setStopFlag") should now be called after PLUMED initialization.
• Several small fixes in documentation.
Version 2.0.2 (Feb 11, 2014)
For users:
• Fixed bug with METAD with INTERVAL and replica exchange, including bias exchange. Now the bias is
correctly computed outside the boundaries. Notice that this is different from what was done in PLUMED 1.3.
Also notice that INTERVAL now works correctly with grids and splines.
• Fixed bug with READ and periodic variables.
• Fixed bug with HISTOGRAM (option USE_ALL_DATA was not working properly).
• Gromacs patch updated to 4.6.5.
• Gromacs patch for 4.6 has been modified to allow for better load balancing when using GPUs.
• Added option 'plumed info –long-version' and 'plumed info –git-version'.
• Added full reference (page/number) to published paper in doc and log.
• Fixed a bug in file backups (only affecting Windows version - thanks to T. Giorgino).
• Added possibility to search in the documentation.
• Several small fixes in documentation and log file.
For developers:
Generated by Doxygen
6
Change Log
• Fixed Makefile dependencies in some auxiliary files in src/lib (∗cmake and ∗inc).
• Changed way modules are linked in src/. E.g. src/colvar/tools/ is not anymore a symlink to src/colvar but
a real directory. (Notice that this introduces a regression: when using plumed as an external library some
include files could not work - this only applies when plumed is installed; also notice that this is fixed in 2.0.3)
• Patch for gromacs 4.6 now also include original code so as to simplify its modification.
• Added option 'plumed patch –save-originals'.
• Fixed regtest regtest/secondarystructure/rt32 to avoid problems with NUMERICAL_DERIVATIVES.
• Removed include graphs in the documentation (too large).
• Several small fixes in documentation.
Version 2.0.3 (June 30, 2014)
For users:
• Now compiles on Blue Gene Q with IBM compilers.
• Fixed bug in CENTER where default WEIGHTS were missing.
• Fixed broken CONTACTMAP with SUM
• Fixed DUMPATOMS with gro file and more than 100k atoms.
• Added CMDIST in CONTACTMAP to emulate plumed1 CMAP.
• Several small fixes in documentation and log file.
For developers:
• Fixed cmd("getBias") to retrieve bias. It was not working with single precision codes and it was not converting
units properly.
• Fixed a regression in 2.0.2 concerning include files from installed plumed (see commit 562d5ea9dfc3).
• Small fix in tools/Random.cpp that allows Random objects to be declared as static.
• Small fix in user-doc compilation, so that if plumed is not found the sourceme.sh file is sourced
• Fixed non-ANSI syntax in a few points and a non-important memory leakage.
• Split cltools/Driver.cpp to make parallel compilation faster.
Version 2.0.4 (Sep 15, 2014)
For users:
• Fixed a bug in BIASVALUE that could produce wrong acceptance with replica exchange simulations.
• Fixed a few innocuous memory leaks.
• Fixed reader for xyz files, that now correctly detects missing columns. Also a related regtest has been
changed.
• Several small fixes in documentation and log file.
For developers:
• Renamed Value.cpp to BiasValue.cpp
Generated by Doxygen
2.2 Version 2.1
7
Version 2.0.5 (Dec 15, 2014)
Warning
This branch is not maintained. Users are invited to upgrade to a newer version
For users:
• Fixed a bug in replica exchange with different Hamiltonians (either lambda-dynamics or plumed XX-hrex
branch) possibly occurring when using charge or mass dependent variables.
• Fixed a bug in analysis (e.g. HISTOGRAM) leading to wrong accumulation of statistics when running a replica
exchange simulation.
• Fixed a bug in the calculation of derivatives in histograms. This should be harmless since people usually only
consider the value in histograms and not the derivatives.
• Fixed an issue in Makefile that could results in problems when patching an MD code with –shared option
(pointed out by Abhi Acharya). This fixes a regression introduced in 2.0.2.
• Small fixes in documentation.
For developers:
• Added warning when performing regtests using an instance of plumed from a different directory
2.2
Version 2.1
Version 2.1.0 (Sep 15, 2014)
Version 2.1 contains several improvements with respect to 2.0. Users currently working with 2.0 should have a
look at the section "Changes leading to incompatible behavior" below and might need tiny adjustments in their
input files. In 2.1 we restored more features of 1.3 that were missing in 2.0, so users still working with 1.←3 could opt for an upgrade. A tutorial explaining how to move from PLUMED 1 to PLUMED 2 is available (see
Moving from PLUMED 1 to PLUMED 2).
Below you find a list of all the changes with respect to version 2.0. Notice that version 2.1 includes already all the
fixes in branch 2.0 up to 2.0.4.
Changes from version 2.0 which are relevant for users:
• Changes leading to incompatible behavior:
– COORDINATION now skips pairs of one atom with itself.
– Labels of quantities calculated by BIASVALUE have changed from label.bias.argname to
label.argname_bias, which is more consistent with steered MD
– Labels of quantities calculated by ABMD have change from label.min_argname to label.argname_min,
which is more consistent with steered MD
– Labels of quantities calculated by PIECEWISE have change from label.argnumber to label.argname←_pfunc, which is more consistent with steered MD
– For multicolvars components calculated with LESS_THAN and MORE_THAN keywords are now labelled lessthan and morethan. This change is necessary as the underscore character now has a special
usage in component names.
Generated by Doxygen
8
Change Log
– In CONTACTMAP components are now labelled label.contact- n.
– The command SPHERE has been replaced by UWALLS.
• New configuration system based on autoconf (use ./configure from root directory). Optional packages are
detected at compile time and correctly enabled or disabled. An internal version of LAPACK and BLAS will be
used if these libraries are not installed.
• New actions:
– SPRINT topological collective variables.
– CH3SHIFTS collective variable.
– POSITION collective variable.
– FIT_TO_TEMPLATE.
– COMMITTOR analysis.
– LOCAL_AVERAGE.
– NLINKS.
– DIHCOR.
– NOE.
– RDC.
– CLASSICAL_MDS.
– XDISTANCES.
– YDISTANCES.
– ZDISTANCES.
– DUMPMULTICOLVAR.
– Crystallization module, including Q3, LOCAL_Q3, Q4, Q6, LOCAL_Q4, LOCAL_Q6, MOLECULES,
SIMPLECUBIC, TETRAHEDRAL and FCCUBIC.
– ENSEMBLE to perform Replica-Averaging on any collective variable.
• New features for existing actions:
– METAD : WALKERS_MPI flag (multiple walkers in a mpi-based multi-replica framework), ACCELE←RATION flag (calculate on the fly the Metadynamics acceleration factor), TAU option (alternative way
to set Gaussian height in well-tempered metadynamics), GRID_SPACING (alternative to GRID_BIN to
set grid spacing). Notice that now one can also omit GRID_BIN and GRID_SPACING when using fixed
size Gaussian, and the grid spacing will be automatically set.
– DISTANCE : added SCALED_COMPONENTS
– COORDINATION : if a single group is provided, it avoids permuted atom indexes and runs at twice the
speed.
– DUMPATOMS : PRECISION option to set number of digits in output file.
– GROUP : NDX_FILE and NDX_GROUP options to import atom lists from ndx (gromacs) files.
– In many multicolvars, MIN and MAX options can be used.
– HISTOGRAM : GRID_SPACING (alternative to GRID_BIN to set grid spacing), FREE-ENERGY flags
in addition to standard probability density, additional option for KERNEL=DISCRETE to accumulate
standard histograms.
– sum_hills : added options –spacing (alternative to –bin to set grid spacing) and –setmintozero to translate the minimum of the output files to zero.
– CONTACTMAP : parallelized and added weights.
• New features in MD patches (require re-patch):
– New patch for Gromacs 5.0
– Gromacs 4.6.X patch updated to 4.6.7
Generated by Doxygen
2.2 Version 2.1
9
– Gromacs 4.6.7 supports COMMITTOR analysis; can be now be used to perform energy minimization;
now passes temperature to PLUMED (this allows temperature to be omitted in some actions, namely
METAD and analysis actions).
Notice that if you use runtime binding it is not compulsory to re-patch, and that all combinations should work
correctly (new/old PLUMED with re-patched/non-re-patched MD code).
• Other new features:
– driver can now read trajectories in many formats using VMD molfile plugin (requires VMD plugins to be
compiled and installed). In case VMD plugins are not installed, the configuration system falls back to
an internal version which implements a minimal list of plugins (gromacs and dcd) (kindly provided by T.
Giorgino).
– switchingfunction : added STRETCH flag.
– Negative strides in atom ranges (e.g. ATOMS=10-1:-3 is expanded to ATOMS=10,7,4,1).
– COORDINATION and DHENERGY with NLIST now work correctly in replica exchange simulations.
– Multicolvars with neighbor lists now work correctly in replica exchange simulations.
– Improved multicolvar neighbor lists.
• Optimizations:
– Root-mean-square deviations with align weights different from displace weights are now considerably
faster. This will affect RMSD calculations plus other variables based on RMSD.
– WHOLEMOLECULES is slightly faster.
– COORDINATION is slightly faster when NN and MM are even and D_0=0.
– Atom scattering with domain decomposition is slightly faster.
– Link cells are now exploited in some multicolvars.
– Derivatives are not calculated unless they are specifically required, because for instance you are adding
a bias.
• Documentation:
– All tutorial material from the recent plumed meeting in Belfast is now in the manual
– Improvements to documentation, including lists of quantities that are output by each action that can be
referenced
– Manual has been re-organized following suggestions received at the plumed meeting.
– An experimental PDF version of the manual is now provided (a link can be found in the documentation
homepage).
Changes from version 2.0 which are relevant for developers:
• Added regtests for plumed as a library (e.g. basic/rt-make-0). plumed command has an additional flag (–
is-installed) to probe if running from a compilation directory or from a fully installed copy (this is needed for
regtests to work properly).
• Improved class Communicator. Many operations can now be done directly on Vectors, Tensors, std::vector
and PLMD::Matrix.
• Modified class RMSD.
• Patches for GPL codes (Quantum Espresso and Gromacs) now also include original code so as to simplify
their modification.
• Fixed dependencies among actions such that it is now possible (and reliable) to use MPI calls inside Action←::prepare()
• colvar/CoordinationBase.cpp has been changed to make it faster. If you devised a class which inherits from
here, consider that CoordinationBase::pairing now needs squared distance instead of distance
Generated by Doxygen
10
Change Log
• It is possible to run "make install" from sub-directories (e.g. from src/colvar)
• There is a small script which disables/enables all optional modules (make mod-light/mod-heavy/mod-reset)
• Added "-q" option to plumed patch
• You can now create new metrics to measure distances from a reference configurations. If you do so such
metrics can then be used in paths straightforwardly
• You can now use multicolvars in tandem with manyrestraints in order to add a large numbers of restraints.
• Can now do multicolvar like things in which each colvar is a vector rather than a scalar.
• Updated script that generated header files so that they properly show years. Notice that the script should new
be run from within a git repository
This list is likely incomplete, if you are developing in PLUMED you are encouraged to follow changes on github.
Version 2.1.1 (Dec 15, 2014)
This release includes all the fixes available in branch 2.0 until 2.0.5.
For users:
• New patch for AMBER 14 (sander module only). This patch should be compatible with any PLUMED 2 version
(including 2.0). It includes most PLUMED features with the notable exception of multi-replica framework.
• Changed definition in arbitrary phase of eigenvectors. This will change the result of some analysis method
where the phase does matter (e.g. CLASSICAL_MDS) and make some regression test better reproducible.
• Fixed a portability issue in BG/P where gettimeofday is not implemented. Notice that this fix implies that one
should execute again ./configure to have plumed timing working correctly.
• CS2Backbone: fixed a bug that resulted in only a fraction of the chemical shifts being printed with WRITE_CS
and parallel simulations (requires to get the last almost updated from SVN)
• NOE: fixed a bug in the replica-averaging
• Fixed a linking issue with ALMOST, where bz2 was always used to link ALMOST to PLUMED even if it is not
compulsory to build ALMOST.
• Fixed a wrong include in the GMX5 patch.
• FUNCPATHMSD can now be used together with CONTACTMAP to define pathways in contact-map space
• Configuration is more verbose, a warning is given if a default option cannot be enabled and an error is given
if an option explicitly enabled cannot be enabled.
• Compilation is less verbose (use "make VERBOSE=1" to have old behavior)
• Small fixes in documentation.
For developers:
• Tests are now performed at every single push on travis-ci.org
• Manual is built and pushed to the online server from travis-ci.org (see developer doc)
• Fixes in developer doc.
Generated by Doxygen
2.2 Version 2.1
11
Version 2.1.2 (Mar 16, 2015)
For users:
• Added two new short tutorials to the manual ( Cambridge tutorial and Munster tutorial ).
• Fixed a severe bug on DRMSD - cutoff values were ignored by PLUMED. Notice that this bug was introduced
in 2.1.0, so that it should not affect the 2.0.x series.
• Fixed a bug affecting LAMMPS patch used with a single processor. Notice that the fix is inside PLUMED, thus
it does not necessarily requires re-patching.
• Sander patch now works with multiple replica (no replica exchange yet). It also contains some fix from J.
Swails.
• GMX5 patch was not working for bias-exchange like cases
• Patching system now checks for the availability of shared/static/runtime version of plumed before patching
• Configure now check better if compiler flag are accepted by the compiler. This makes configure on bluegene
more robust.
• Sourceme.sh now sets proper library path in linux also.
Version 2.1.3 (June 30, 2015)
For users:
• Fixed bug in ENSEMBLE derivatives when more than 1 argument was provided
• Fixed bug in GHOST : virial is now computed correctly.
• Fixed a serious bug in virial communicated from plumed to gromacs, for both gromacs versions 4.6 and 5.←0. See #132. This fix requires gromacs to be re-patched and could be very important if you run biased
simulations in the NPT ensemble.
• Fixed a bug in the virial computed with FIT_TO_TEMPLATE when the reference pdb had center non located
at the origin.
• Fixed a bug in the the forces computed with FIT_TO_TEMPLATE when used in combination with COM,
CENTER, or GHOST
• Fixed a bug that could lead plumed to be stuck with domain decomposition in some extreme case (one domain
with all atoms, other domains empty).
• Fixed a bug when COMBINE or MATHEVAL are used with PERIODIC keyword. Now when PERIODIC
keyword is used the result of the calculation is brought within the periodicity domain. See #139.
• Fixed a bug related to RANDOM_EXCHANGES followed by INCLUDE
• Fixed bug in derivatives of histogram bead with triangular kernels
• Updated gromacs patch 4.5.5 to 4.5.7
• Updated internal molfile plugins to VMD 1.9.2.
• Included crd and crdbox formats to internal molfile.
• Added –natoms to driver . This is required to read coordinate files with VMD plugins when number of atoms
is not present (e.g. amber crd files)
• Added the checks in the driver to detect cases where molinfo does not provide box information (e.g. pdb).
Generated by Doxygen
12
Change Log
• Added support for readdir_r when available, which makes opening files thread safe.
• CFLAGS now include -fPIC by default
• Added a warning when using METAD without grids with a large number of hills.
• Fixes in user documentation.
For developers:
• Allow external VMD plugins to be detected with –has-external-molfile. This is required to enable some regtest
with amber files.
• Added –dump-full-virial to driver
• Allow definition of variables where some of the components have derivatives and some haven't (#131).
• Improved travis tests with more debug options.
• Improved some regtest to check out-of-diagonal virial components
• Improved make cppcheck options.
• Fixes in developer documentation.
Version 2.1.4 (Oct 13, 2015)
For users:
• Fixed NAMD patch. Masses and charges were not passed correctly, thus resulting in wrong COM or CENTER
with MASS. This fix required re-patching NAMD. Notice that this bug was present also in v2.0 but in a different
form. More information here (#162), including a workaround that allows masses to be fixed without repatching.
• When installing with PLUMED_LIBSUFFIX an underscore is used as separator instead of a dash. E.g. make
install PLUMED_LIBSUFFIX=2.1 will result in an executable named plumed_v2.1. This fix a
potential problem (see Installation).
• Fixed erroneously reported message about MPI at the end of ./configure.
• Changed warning message about undocumented components.
• PLUMED now says in the log file if it was compiled from a dirty git repository.
• Fixed a problem leading to rare random crashes when using METAD with WALKERS_MPI and multiple
processors per replica.
• Small change in numerical accuracy of lattice reduction. Should be more robust when running with highly
optimizing compilers.
• Fixed a bug in normalization of kernel functions. This affects HISTOGRAM If these actions were used with
previous versions of the code care should be taken when analyzing the results.
• Fixed a bug in derivatives of kernel functions with non-diagonal covariance matrices. This affects the derivatives output by sum_hills
Generated by Doxygen
2.3 Version 2.2
13
Version 2.1.5 (Jan 18, 2016)
Warning
This branch is not maintained. Users are invited to upgrade to a newer version
For users:
• PLUMED now reports an error when using HISTOGRAM with FREE-ENERGY without USE_ALL_DATA. See
#175
• Fixed a bug in configure together with –enable-almost. The check for lbz2 library was not working properly.
2.3
Version 2.2
Version 2.2 (Oct 13, 2015)
Version 2.2 contains several improvements with respect to 2.1. Users currently working with 2.1 should have a
look at the section "Changes leading to incompatible behavior" below and might need tiny adjustments in their
input files. In 2.2 we restored more features of 1.3 that were missing in 2.1, so users still working with 1.←3 could opt for an upgrade. A tutorial explaining how to move from PLUMED 1 to PLUMED 2 is available (see
Moving from PLUMED 1 to PLUMED 2).
Below you find a list of all the changes with respect to version 2.1. Notice that version 2.2 includes already all the
fixes in branch 2.1 up to 2.1.4 indicated in Version 2.1 .
Changes from version 2.1 which are relevant for users:
• Changes leading to incompatible behavior:
– Labels of quantities calculates by SPRINT have changed from label.coord_num to label.coord-num
– METAD with WALKERS_MPI now writes a single hills file, without suffixes
– removed the ./configure.sh script of v2.0.x, now plumed can only be configured using autotools (./configure)
– COM, CENTER, and GYRATION now automatically make molecules whole. In case you do not want
them to do it, use NOPBC flag, which recovers plumed 2.1 behavior
– Some MD code could now automatically trigger restart (e.g. gromacs when starting from cpt files). This
can be overwritten using RESTART NO.
– Replica suffixes are now added by PLUMED before extension (e.g. use plumed.0.dat instead of
plumed.dat.0)
– When using switchingfunction the STRETCH keyword is now implicit. NOSTRETCH is available to
enforce the old behavior.
• Module activation can now be controlled during configure with --enable-modules option.
• Almost complete refactoring of installation procedure. Now DESTDIR and other standard autoconf directories
(e.g. bindir) are completely supported. Additionally, everything should work properly also when directory
names include spaces (#157). Finally, compiler is not invoked on install unless path are explicitly changed
(#107).
• Related to installation refactoring, upon install a previously installed PLUMED is not removed. This is to avoid
data loss if prefix variable is not properly set
Generated by Doxygen
14
Change Log
• Several changes have been made in the Makefile.conf that makes it not compatible with those packaged with
plumed 2.0/2.1. Please use ./configure to generate a new configuration file.
• Added partial OpenMP parallelization, see OpenMP
• Added multiple time step integration for bias potentials, see Multiple time stepping
• Link cells are now used in all multicolvars that involve switchingfunction. The link cell cutoff is set equal to 2.∗
d
. Where d
is the (user-specified) point at which the switching function goes to zero. Users should
always set this parameter when using a switching function in order to achieve optimal performance.
max
max
• DHENERGY option is no longer possible within DISTANCES. You can still calculate the DHENERGY colvar
by using DHENERGY
• Reweighting in the manner described in [3] is now possible using a combination of the METAD and
HISTOGRAM actions. The relevant keywords in METAD are REWEIGHTING_NGRID and REWEIGHT←ING_NHILLS. The c(t) and the appropriate weight to apply to the configurations are given by the values
labeled rct and rbias.
• News in configure and install:
– ./configure now allows external BLAS to be used with internal LAPACK. This is done automatically if
only BLAS are available, and can be enforced with –disable-external-lapack.
– ./configure supports –program-prefix, –program-suffix, and –program-transform-name.
– make install supports DESTDIR and prefix.
– Environment variables PLUMED_LIBSUFFIX and PLUMED_PREFIX are deprecated and will be removed in a later version.
• New actions
– DUMPMASSCHARGE to dump a file with mass and charges during MD.
– EFFECTIVE_ENERGY_DRIFT to check that plumed forces are not screwing the MD integrator.
– EXTENDED_LAGRANGIAN : in combination with METAD it implements metadynamics with Extended
Lagrangian; standalone it implements TAMD/dAFED.
– DFSCLUSTERING calculate the size of clusters
– DUMPMULTICOLVAR print out a multicolvar
– MFILTER_LESS filter multicolvar by the value of the colvar
– MFILTER_MORE
– MFILTER_BETWEEN
– PCARMSD PCA collective variables using OPTIMAL rmsd measure
– PCAVARS PCA collective variables using any one of the measures in reference
– GRADIENT can be used to calculate the gradient of a quantity. Used to drive nucleation
– CAVITY
– PUCKERING implemented for 5-membered rings (thanks to Alejandro Gil-Ley).
– WRAPAROUND to fix periodic boundary conditions.
• New features for existing actions:
– Keywords UPDATE_FROM and UPDATE_UNTIL to limit update step in a defined time window, available
only for actions where it would be useful.
– Keyword UNNORMALIZED for HISTOGRAM.
– Possibility to use Tiwary-Parrinello reweighting for METAD
– Keywords for GROUP (REMOVE, SORT, UNIQUE) to allow more flexible editing of groups.
– DUMPATOMS now supports dumping xtc and trr files (requires xdrfile library).
– driver can now read xtc and trr files also with xdrfile library.
Generated by Doxygen
2.3 Version 2.2
15
– driver accepts a –mc flag to read charges and masses from a file produced during molecular dynamics
with DUMPMASSCHARGE
– Possibility to enable or disable RESTART on a per action basis, available only for actions where it would
be useful.
– MOLINFO now supports many more special names for rna and dna (thanks to Alejandro Gil-Ley).
– VMEAN and VSUM allow one to calculate the sum of a set of vectors calculated by VectorMultiColvar.
Note these can also be used in tandem with AROUND or MFILTER_MORE to calculate the average
vector within a particular part of the cell or the average vector among those that have a magnitude
greater than some tolerance
– New way of calculating the minimum value in multicolvars (ALT_MIN). This is less susceptible to overflow
for certain values of β .
- New keywords for calculating the LOWEST and HIGHEST colvar calculated by a multicolvar
– Added components to DIPOLE (#160).
• Other changes:
– File reader now supports dos newlines as well as files with no endline at the end.
For developers:
• In order to be able to use openMP parallelism within multicolvar, secondarystructure, manyrestraints and
crystallisation we had to make some substantial changes to the code that underlies these routines that is
contained within vesselbase. In particular we needed to get rid of the derivatives and buffer private variables in
the class ActionWithVessel. As a consequence the derivatives calculated in the various performTask methods
are stored in an object of type MultiValue. Within multicolvar this is contained within an object of type Atom←ValuePack, which stores information on the atom indices. If you have implemented a new multicolvar it should
be relatively straightforward to translate them so they can exploit this new version of the code. Look at what
has been done to the other multicolvars in there for guidance. Sorry for any inconvenience caused.
• Changed the logic of several PLUMED ifdef macros so as to make them consistent. Now every feature based
on external libraries is identified by a __PLUMED_HAS_∗ macro.
Version 2.2.1 (Jan 18, 2016)
For users:
• PBMETAD implement the new Parallel Bias Metadynamics flavor of the Metadynamics sampling method.
• PLUMED now reports an error when using HISTOGRAM with UNNORMALIZED without USE_ALL_DATA.
See #175
• Fixed a bug in configure together with –enable-almost. The check for lbz2 library was not working properly.
• Fixed a bug in install procedure that was introducing an error in linking with CP2K.
• Fixed a bug that sometimes was preventing the printing of a useful error message.
For developers:
• Vector and Tensor now support direct output with <<.
• Added some missing matmul operation Vector and Tensor.
• ./configure is automatically relaunched when changing ./configure or Makefile.conf. This makes it more robust
to switch between branches.
Generated by Doxygen
16
Change Log
Version 2.2.2 (Apr 13, 2016)
For users:
• MOLINFO for RNA accepts more residue names, see #180.
• added two mpi barries (one was missing in PBMetaD for multiple walkers) to help syncronise initialisation
• Fixed a bug in internal stopwatches that was making DEBUG logRequestedAtoms not working
• Some multicolvars (including BRIDGE, ANGLES, and INPLANEDISTANCES) now crashes if one asks for too
many atoms, see #185.
• Optimisations (activation of the dependencies, secondary structures, DRMSD)
• Fixed a performance regression with RMSD=OPTIMAL-FAST
• Fixed a bug in the normalization of kernel functions (relevant for HISTOGRAM).
• Fixed a regression introduced in v2.2 that was making METAD with non-MPI multiple walkers crash if reading
frequently. See #190
• Updated patch for gromacs 5.x. Patches for gromacs 5.0 and 5.1 have been fixed so as to allow patching in
runtime mode.
• Possibility to control manual generation (including pdf) from ./configure. Pdf manual is now off by default.
Notice that on travis CI it is still generated.
For developers:
• Fixed a bug in the interpretation of cmd strings. Namely, an erroneous string was not triggering an error. This
is harmless for MD codes properly patched, but could have introduced problems in MD codes with typoes in
cmd strings.
• ./configure is not automatically relaunched anymore when doing make clean.
Version 2.2.3 (Jun 30, 2016)
For users:
• Updated patches for gromacs 5.1.x and 5.0.x to fix a problem when plumed was trying to write to an already
closed gromacs log file.
• When looking for a value outside the GRID now the error include the name of the responsible collective
variable
• Numerical check in LatticeReduction made less picky. This should solve some of the internal errors reported
by LatticeReduction.cpp when using aggressive compilers.
• Files are now flushed at the correct step. Before this fix, they were flushed at the step before the requested
one (e.g. with FLUSH STRIDE=100 at step 99, 199, etc).
• In METAD, INTERVAL with periodic variables now report an error.
• LOAD now works also when plumed is installed with a suffix.
• Added --md-root option to plumed patch which allows it to be run from a directory different from the
one where the md code is located.
• Wham script in Munster tutorial tutorial now writes weights in scientific notation.
Generated by Doxygen
2.3 Version 2.2
17
For developers:
• ./configure checks if dependencies can be generated. If not, they are disabled.
• Added –disable-dependency-tracking to ./configure
• Added a make target all_plus_doc that builds both code and docs.
• Added possibility to set a default location for plumed library in runtime binding. If the plumed wrapped is
compiled with -D__PLUMED_DEFAULT_KERNEL=/path/libplumedKernel.so, then if the env var
PLUMED_KERNEL is undefined or empty PLUMED will look in the path at compile time.
• Tentative port files are now available at this link. They can be used to install PLUMED using MacPorts.
Version 2.2.4 (Dec 12, 2016)
For users:
• Fix a bug in PBMETAD when biasing periodic and not periodic collective variables at the same time
• GSL library is now treated by ./configure in the same way as other libraries, that is -lgsl
-lgslcblas are only added if necessary.
• Fix a bug in METAD when using INTERVAL and ADAPTIVE gaussians at the same time
• Updated gromacs patch for 5.1.x to 5.1.4
• Fix a performance regression in the calculate loop where derivatives and forces were set to zero even if an
action was not active, this is relevant for postprocessing and for the on-the-fly analysis
• Torsion calculation has been made slightly faster and improved so as to provide correct derivatives even for
special angles (e.g. +pi/2 and -pi/2).
For developers:
• Macports portile is now tested on travis at every plumed push.
Version 2.2.5 (Mar 31, 2017)
Warning
This branch is not maintained. Users are invited to upgrade to a newer version
For users:
• Fixed a problem with large step numbers in driver (see #209).
• Fixed a problem leading to crashes when using switching functions without cutoff with some compiler (see
#210).
• Fixed a bug when using FIT_TO_TEMPLATE and domain decomposition (see #214).
• Added an automatic flush of HILLS files when using METAD with file-based multiple walkers.
• Root dir is logged to allow easier debugging of problems.
Generated by Doxygen
18
2.4
Change Log
Version 2.3
Version 2.3 (Dec 12, 2016)
Version 2.3 contains several improvements with respect to 2.2. Users currently working with 2.2 should have a look
at the section "Changes leading to incompatible behavior" below and might need tiny adjustments in their input files.
Below you find a list of all the changes with respect to version 2.2. Notice that version 2.3 includes already all the
fixes in branch 2.2 up to 2.2.3 indicated in Version 2.2 .
Changes from version 2.2 which are relevant for users:
• Changes leading to incompatible behavior:
– COMMITTOR can now be used to define multiple basins, but the syntax has been changed
– Syntax for SPRINT and DFSCLUSTERING has changed. We have separated the Actions that calculate
the contact matrix from these actions. These actions thus now take a contact matrix as input. This
means that we these actions can be used with contact matrices that measures whether or not a pair
of atoms are hydrogen bonded. For more details on this see Exploiting contact matrices. For clustering the output can now be passed to the actions CLUSTER_PROPERTIES, CLUSTER_DIAMETER,
CLUSTER_NATOMS, OUTPUT_CLUSTER and CLUSTER_DISTRIBUTION. These provide various
different kinds of information about the connected components found by clustering
– In driver masses and charges are set by default to NaN. This makes it less likely to do mistakes trying
to compute centers of mass or electrostatic-dependent variables when masses or charges were not set.
To compute these variables from the driver you are now forced to use --pdb or --mc.
– In rational switching functions, by default MM is twice NN. This is valid both in switchingfunction with
expanded syntax and when specifying MM on e.g. COORDINATION
– Patch script plumed patch now patches by default with --shared. This should make the procedure more robust (see #186).
– Faster GYRATION but new default behavior is not mass weighted
– When using HISTOGRAM you now output the accumulated grid using DUMPGRID or DUMPCUBE to
get the free energy you use the method CONVERT_TO_FES. These changes allow one to use grids
calculated within PLUMED in a work flow of tasks similarly to the way that you can currently use Values.
– The way that reweighting is performed is now different.
There are three separate actions
REWEIGHT_BIAS, REWEIGHT_TEMP and REWEIGHT_METAD. These actions calculate the quantities that were calculated using the keywords REWEIGHT_BIAS and REWEIGHT_TEMP that used to
appear in the old HISTOGRAM method. Now those these methods can be used in any methods that
calculate ensemble averages for example HISTOGRAM and AVERAGE
– Manual is now build with locally compiled plumed
– Removed CH3SHIFT
– CS2BACKBONE is now native in PLUMED removing the need to link ALMOST, small syntax differences
– CS2BACKBONE, NOE, RDC, removed the keyword ENSEMBLE: now ensemble averages can only be
calculated using ENSEMBLE
– RDC, syntax changes
– It is not possible anymore to select modules using modulename.on and modulename.off files.
Use ./configure --enable-modules instead.
– Removed IMD modules. In case someone is interested in restoring it, please contact the PLUMED
developers.
• New actions:
– FIXEDATOM
– HBOND_MATRIX
Generated by Doxygen
2.4 Version 2.3
19
– CLUSTER_PROPERTIES
– CLUSTER_DIAMETER
– CLUSTER_NATOMS
– OUTPUT_CLUSTER
– CLUSTER_DISTRIBUTION
– ROWSUMS
– COLUMNSUMS
– UPDATE_IF
– DUMPGRID
– DUMPCUBE
– CONVERT_TO_FES
– INTERPOLATE_GRID
– FIND_CONTOUR
– FIND_SPHERICAL_CONTOUR
– FIND_CONTOUR_SURFACE
– AVERAGE
– REWEIGHT_BIAS
– REWEIGHT_TEMP
– REWEIGHT_METAD
– PCA
– PRE
– STATS
– METAINFERENCE
– LOCALENSEMBLE
– FRET
– RESET_CELL
– JCOUPLING
– ERMSD
• New features in MD patches (require re-patch):
– Patch for amber 14 now passes charges with appropriate units (fixes #165). Notice that the patch is
still backward compatible with older PLUMED version, but the charges will only be passed when using
PLUMED 2.3 or later.
– Patch for GROMACS 5.1 incorporates Hamiltonian replica exchange, see Using Hamiltonian replica exchange with GROM
– Gromacs 2016, 5.1.x, 5.0.x, flush the plumed output files upon checkpointing
– Added patch for Gromacs 2016.1
– gromacs 5.1.x patch updated to 5.1.4
– Removed the patch for Gromacs 4.6.x
– LAMMPS patch updated to support multiple walkers and report plumed bias to LAMMPS (thanks to
Pablo Piaggi).
• New features for existing actions:
– The SPECIES and SPECIESA keyword in MultiColvars can now take a multicolvar as input. This allows
one to calculate quantities such as the Q4 parameters for those atoms that have a coordination number
greater than x.
– Added MATHEVAL type in switchingfunction
– Added Q type native contacts in switchingfunction (thanks to Jan Domanski).
Generated by Doxygen
20
Change Log
– COMMITTOR can now be used to define multiple basins
– The number of atoms admitted in BRIDGE has been significantly increased, see #185.
– driver now allows –trajectory-stride to be set to zero when reading with –ixtc/–itrr. In this case, step
number is read from the trajectory file.
– METAD and PBMETAD can now be restarted from a GRID
– Added keywords TARGET and DAMPFACTOR in METAD
– When using METAD with file-based multiple walkers and parallel jobs (i.e. mpirun) extra suffix is not
added (thanks to Marco De La Pierre).
– ENSEMBLE added keywords for weighted averages, and calculation of higher momenta
– MOLINFO now allows single atoms to be picked by name.
– FIT_TO_TEMPLATE now supports optimal alignment.
– CONSTANT added the possibility of storing more values as components with or without derivatives
– PUCKERING now supports 6 membered rings.
– Extended checkpoint infrastructure, now METAD and PBMETAD will write GRIDS also on checkpoint
step (only the GROMACS patch is currently using the checkpointing interface)
• Other features:
– Added a plumed-config command line tool. Can be used to inspect configuration also when cross
compiling.
– Added a --mpi option to plumed, symmetric to --no-mpi. Currently, it has no effect (MPI is
initialized by default when available).
– PLUMED now generate a VIM syntax file, see Using VIM syntax file
– The backward cycle is now parallelized in MPI/OpenMP in case many collective variables are used.
– GSL library is now searched by default during ./configure.
– Tutorials have been (partially) updated to reflect some of the changes in the syntax
– Parser now reports errors when passing numbers that cannot be parsed instead of silently replacing
their default value. See #104.
– More and more documentation
• Bug fixes:
• Fixed a bug in PBMETAD that was preventing the writing of GRIDS if a hill was not added in that same step
For developers:
• IMPORTANT: BIAS can now be BIASED as well, this changes can lead to some incompatibility: now the
"bias" component is always defined automatically by the constructor of Bias as a componentWithDerivatives,
derivatives are automatically obtained by forces. The main change is that you don't have to define the bias
component anymore in your constructor and that you can use setBias(value) to set the value of the bias
component in calculate.
• Added new strings for plumed cmd: setMDMassUnits, setMDChargeUnits, readInputLine, performCalcNo←Update, update and doCheckPoint.
• Easier to add actions with multiple arguments
• New functions to access local quantities in domain decomposition
• Active modules to enable regtests are chosen using plumed config.
• A script is available to check if source code complies plumed standard. Notice that this script is run together
with cppcheck on travis-ci.
• Cppcheck on travis-ci has been updated to 1.75. Several small issues triggering errors on 1.75 were fixed
(e.g. structures passed by value are now passed by const ref) and false positives marked as such.
• Added coverage scan.
Generated by Doxygen
2.4 Version 2.3
21
Version 2.3.1 (Mar 31, 2017)
• Fix to FIT_TO_TEMPLATE as in 2.2.5. Notice that in 2.3.0 also the case with TYPE=OPTIMAL was affected.
This is fixed now.
• small change in CS2BACKBONE to symmetrize the ring current contribution with respect to ring rotations
(also faster)
• fixed plumed-config that was not working.
• log file points to the config.txt files to allow users to check which features were available in that compiled
version.
• make clean in root dir now also cleans vim sub-directory.
• Updated gromacs patch to version 2016.3
For developers:
• Cppcheck on travis-ci has been updated to 1.77.
• Doxygen on travis-ci has been updated to 1.8.13
Version 2.3.2 (Jun 12, 2017)
See branch v2.3 on git repository.
• Resolved problem with nan in SMAC with SPECIESA and SPECIESB involving molecules that are the same
• PDB reader is now able to read files with dos newlines (see #223).
• Fixed bug in CS2BACKBONE (v2.3.1) related to ring currents of HIS and TRP
• Fixed bug in if condition in PCAVARS so that you can run with only one eigenvector defined in input
• Fixed bug with timers in sum_hills #194.
• Fixed bug when using MOVINGRESTRAINT with periodic variables such as TORSION #225.
• Fixed bug in HBOND_MATRIX that used to appear when you used DONORS and ACCEPTORS with same
numbers of atoms
• Fixed bug in DISTANCES that appears when using BETWEEN and link cells.
• Prevented users from causing segfaults by storing derivatives without LOWMEM flag. In these cases PLU←MED crashes with meaningful errors.
• Fixed bug in HISTOGRAM that causes NaNs when using KERNEL=DISCRETE option
• Fixed a bug in the parser related to braces, see #229
• Fixed a bug that appeared when using Q3, Q4 and Q6 with LOWEST or HIGHEST flag
• Fixed a bug that appears when you use MFILTER_LESS as input to COORDINATIONNUMBER with SPE←CIESA and SPECIESB flags
• Fixed a bug that was making flushing when gromacs checkpoints not functional (thanks to Summer Snow).
• Fixed a bug affecting EXTENDED_LAGRANGIAN and METAD with ADAPT=DIFF when using an argument
with periodicity (min,max) such that min is different from -max. This does not affect normal TORSION, but
would affect PUCKERING component phi with 6-membered rings. In addition, it would affect any variable that
is created by the user with a periodicity domain not symmetric around zero. See #235 (thanks to Summer
Snow for reporting this bug).
Generated by Doxygen
22
Change Log
• Fixed numerical issue leading to simulations stuck (LatticeReduction problem) with intel compiler and large
simulation cells.
• Fixed a bug affecting LOCAL_AVERAGE and outputting all multicolvars calculated by Q6 with
DUMPMULTICOLVAR
• plumed info --user-doc and plumed info --developer-doc now fall back to online manual when local doc is not installed, see #240.
For developers:
• IMPORTANT: we started to enforce code formatting using astyle. Check the developer documentation to
learn how to take care of not-yet-formatted branches.
• plumedcheck validation has been made stricter. All the checks are now described in the developer manual.
• New flag --disable-libsearch for configure, allowing an easier control of linked libraries when
installing PLUMED with a package manager such as MacPorts.
• Added --disable-static-patch to ./configure to disable tests related to static patching. It can
be used when static patching is not needed to make sure a wrong c++ library is not linked by mistake.
• Using install_name_tool to fix the name of the installed library on OSX. Allows linking the PLUMED
shared library without explicitly setting DYLD_LIBRARY_PATH.
• Added environment variable PLUMED_ASYNC_SHARE to enforce synchronous/asynchronous atom sharing
(mostly for debug purpose).
• On travis-ci, using ccache to speedup builds.
• On travis-ci, added a regtest using Docker with gcc6 and MPI.
• On travis-ci, docs for unofficial or unsupported branches are set not to be indexed by search engines (see
#239)
• Cppcheck on travis-ci has been updated to 1.79.
Version 2.3.3 (Oct 3, 2017)
For users:
• Fixed a bug in switchingfunction MATHEVAL, leading to inconsistent results when using OpenMP with multiple threads (see #249).
• FIT_TO_TEMPLATE now reports when it is used with a reference file with zero weights.
• Fixed logging of UNITS (thanks to Omar Valsson).
• Fixed a possible bug with EFFECTIVE_ENERGY_DRIFT and domain decomposition with a domain containing zero atoms.
For developers:
• Fixed a bug in ./configure --disable-libsearch when searching for molfile plugins.
• Cppcheck on travis-ci has been updated to 1.80.
• Configure script now has a list of better alternatives to find a working ld -r -o tool to merge object files.
This solves linking issues on some peculiar systems (see #291, thanks to Massimiliano Culpo).
• Using install_name_tool also on non-installed libraries. This makes it possible to link them and later
find them without explicitly setting DYLD_LIBRARY_PATH. This should also make the DYLD_LIBRARY←_PATH irrelevant. Notice that DYLD_LIBRARY_PATH is not well behaved in OSX El Capitan.
Generated by Doxygen
2.4 Version 2.3
23
Version 2.3.4 (Dec 15, 2017)
For users:
• GROMACS patch updated to gromacs-2016.4. This patch was also fixed in order to properly work with
ENERGY (see #316) and to implement -hrex option (see #197).
• Patch for GROMACS 5.1.4 updated to fix an error with ENERGY (see #316).
• Solved a bug in ERMSD leading to incorrect results when using non-default length units (e.g. with UNITS
LENGTH=A).
For developers:
• Regtest script also reports when exitcode different from zero is returned.
• Patch script reports errors returning a nonzero exit code.
• cppcheck update to 1.81
• Solved small bug in stored PLUMED_ROOT directory as obtained from statically patched MD codes. Namely,
the compilation directory was stored rather than the installation one.
Version 2.3.5 (Mar 2, 2018)
For users:
• Fixed plumed partial_tempering to agree with GROMACS conventions for the choice of dihedral
angles (see #337). Should be irrelevant for the vast majority of cases.
• Fixed small bug in regexp parser - the part outside the parentheses was just ignored.
For developers:
• Doxygen on travis-ci has been updated to 1.8.14.
• Embedded astyle updated to 3.1.
• make clean now correctly removes the src/lib/plumed executable.
Version 2.3.6 (Jul 2, 2018)
For users:
• Fixed a problem leading to NaN derivatives of switchingfunction Q when distance between two atoms is large.
• GROMACS patch updated to gromacs-2016.5.
• ./configure crashes if prefix is set to present working directory (notice that this choice was already
leading to issues).
• DUMPATOMS reports an error when trying to write xtc/xdr files without the xdrfile library installed.
Generated by Doxygen
24
Change Log
• Fixed a bug appearing when using PATH or GPROPERTYMAP with virtual atoms without simultaneously
using the same atoms in a different action.
• Fixed incorrect format of the pdb file written by PCA (see #363).
• Fixed behavior of natural units. When an MD code asks for natural units, it is not necessary to also set units
within PLUMED using UNITS (see #364).
For developers:
• Fixed small issue in debug options of driver (see #245).
• plumed patch -e now accepts a name closely matching the patch name (e.g. plumed patch -e
gromacs2016.5 will try to patch even if the stored patch is for gromacs-2016.4). This simplifies
managing Portfiles. Nothing changes when picking the patch from the interactive menu.
• Install newer ccache on travis-ci, build faster.
• Small fix in provided env modules (PLUMED_VIMPATH is set also when shared libraries are disabled).
Version 2.3.7 (Oct 5, 2018)
For users:
• Fixed flag DETAILED_TIMERS in DEBUG (flag was ignored and detailed timers always written).
• Small fix in DUMPMASSCHARGE (atoms are now correctly requested only at first step).
Version 2.3.8 (Dec 19, 2018)
Warning
This branch is not maintained. Users are invited to upgrade to a newer version
For users:
• Fixed some openMP regression (some related to the whole codes and some specifics for Coordination and
Multicolvar), this were compiler dependent so not all users may have experienced them
• Fixed an issue with CS2BACKBONE when more than 2 chains were used
• Fixed memory leak in RDC.
• Fixed segmentation fault with more than two CVs in reweighting METAD (see #399, thanks to Fiskissimo).
For developers:
• Small fix in LDFLAGS when enabling coverage.
• Fixed order of flags in tests for static linking done by configure (see #407).
• Fixed the way paths are hard-coded so as to facilitate conda packaging (see #416).
∗/
Generated by Doxygen
2.5 Version 2.4
2.5
25
Version 2.4
Version 2.4 (Dec 15, 2017)
Version 2.4 contains several improvements with respect to 2.3. Users currently working with 2.3 should have a look
at the section "Changes leading to incompatible behavior" below and might need tiny adjustments in their input files.
Notice that version 2.4 includes already all the fixes in branch 2.3 up to 2.3.3 indicated in Version 2.3 .
Changes from version 2.3 which are relevant for users:
• Changes leading to incompatible behavior:
– A c++11 compliant compiler is required (see #212). This should mean:
* gcc 4.8
* clang 3.3
* intel 15 Since the number of c++11 features that we use is limited, older compilers might work as
well.
– The meaning of BIASFACTOR=1 in METAD has been modified and can now be used to indicate unbiased simulations. Non-well-tempered metadynamics is BIASFACTOR=-1, which is the new default
value. Notice that this has an implication on the bias factor written in the HILLS file when doing nonwell-tempered metadynamics.
– Due to a change in COMMITTOR, the format of its output file has been slightly changed.
– HISTOGRAM : When using weights default is now to output histogram divided by number of frames
from which data was taken. In addition the UNORMALIZED flag has been replaced with the keyword
NORMALIZATION, which can be set equal to true, false or ndata.
– All switching functions are now stretched by default, also when using the "simple syntax" (e.g. COO←RDINATION NN=6). Switching functions were already stretched by default when using the advanced
syntax (e.g. COORDINATION SWITCH={}) since version 2.2. Notice that this will introduce small
numerical differences in the computed switching functions.
• New modules:
– A new PLUMED-ISDB module have been included, this module includes a number of CVs to calculate
experimental data with the internal ability to also calculate a METAINFERENCE score.
* New actions include:
· EMMI
· SAXS
· RESCALE, SELECT, SELECTOR
* Updated actions include:
· CS2BACKBONE
· FRET
· JCOUPLING
· METAINFERENCE
· NOE
· PRE
· RDC, PCS
· PBMETAD
– A new EDS module have been included, contributed by Glen Hocky and Andrew White. This module
implements the following methods:
* EDS
– A new DRR module have been included, contributed by Haochuan Chen and Haohao Fu. This module
implements the following methods:
Generated by Doxygen
26
Change Log
* DRR
* drr_tool
– A new VES module have been included, contributed by Omar Valsson. This module implements the
following methods:
* BF_CHEBYSHEV
* BF_COMBINED
* BF_COSINE
* BF_CUSTOM
* BF_FOURIER
* BF_LEGENDRE
* BF_POWERS
* BF_SINE
* OPT_AVERAGED_SGD
* OPT_DUMMY
* TD_CHI
* TD_CHISQUARED
* TD_CUSTOM
* TD_EXPONENTIAL
* TD_EXPONENTIALLY_MODIFIED_GAUSSIAN
* TD_GAUSSIAN
* TD_GENERALIZED_EXTREME_VALUE
* TD_GENERALIZED_NORMAL
* TD_GRID
* TD_LINEAR_COMBINATION
* TD_PRODUCT_COMBINATION
* TD_PRODUCT_DISTRIBUTION
* TD_UNIFORM
* TD_VONMISES
* TD_WELLTEMPERED
* VES_LINEAR_EXPANSION
* VES_OUTPUT_BASISFUNCTIONS
* VES_OUTPUT_FES
* VES_OUTPUT_TARGET_DISTRIBUTION
* ves_md_linearexpansion
• New collective variables:
– DIMER (thanks to Marco Nava).
– EEFSOLV : EEF1 implicit solvent solvation energy
– ADAPTIVE_PATH : Adaptive path variables using the method from [4]
• New actions:
– INENVELOPE
– TOPOLOGY_MATRIX
– BOND_DIRECTIONS
– DUMPGRAPH
– GRID_TO_XYZ
– INTEGRATE_GRID
– LWALLS
– MAXENT
Generated by Doxygen
2.5 Version 2.4
27
– MCOLV_COMBINE
– MCOLV_PRODUCT
– POLYMER_ANGLES
– XANGLES , YANGLES , ZANGLES
– XYTORSIONS , XZTORSIONS , YXTORSIONS , YZTORSIONS , ZXTORSIONS , and ZYTORSIONS
• New command line tools:
– pesmd : Tool for performing Langevin dynamics on an energy landscape that is specified using a PL←UMED input file
– pathtools
• Other changes:
– Sharing coordinates and applying force is now faster (in some cases these can result in much better
scaling of the performances in parallel).
– COMMITTOR : new flag to use committor to keep track of the visited basins without stopping the
simulation
– PBMETAD : multiple walkers using files (thanks to Marco De La Pierre).
– PBMETAD : adaptive Gaussian kernels
– PBMETAD : default names for GRID and FILE (useful with many collective variables)
– METAD : BIASFACTOR=1 is allowed and performs unbiased sampling. HILLS file can be used to
recover free energy also in this case.
– METAD : a RECT option is available that allows setting an array of bias factors, one for each replica.
– METAD : added options to perform Transition Tempered Metadynamics (thanks to James Dama)
– PATHMSD and PROPERTYMAP now support alignment to a close structure (thanks to Jana
Pazurikova)
– PDB files with more than 100k atoms can now be read using hybrid 36 format, see #226.
– Added lepton support. Set env var export PLUMED_USE_LEPTON=yes to activate lepton as a
matheval replacement in MATHEVAL, CUSTOM, and MATHEVAL switching function. Notice that in
v2.5 matheval support will be dropped and all these keywords will use lepton. See #244.
– When parsing constants, PLUMED uses lepton library. This allows to pass arguments such as HEIG←HT=exp(0.5) (see Parsing constants).
– CUSTOM function has been added as an alias to MATHEVAL .
– Trajectories read in driver also support the usual replica convention, that is if trajectory with replica suffix
is not found the driver will look for a trajectory without the replica suffix.
– A new syntax (@replicas:) can be used to specify different arguments for different replicas (see
Special replica syntax).
– Internal molfile implementation has been updated to VMD 1.9.3.
– Examples in the documentation now have syntax highlighting and links to the documentation of used
actions.
– COORDINATIONNUMBER : Added option to have pairwise distance moments of coordination number
in the multicolvar module
– GROMACS patch updated to gromacs-2016.4
– Implemented HREX for gromacs-2016.4.
– Added patch for Quantum ESPRESSO 6.2 (thanks to Ralf Meyer).
– Fixed a bug in LOCAL_AVERAGE which appears when you use SPECIESA and SPECIESB keywords
instead of just SPECIES
– Added possibility to pass --kt from driver.
Changes from version 2.3 which are relevant for developers:
Generated by Doxygen
28
Change Log
• A few fixes has been made to improve exception safety. Although we still cannot declare PLUMED totally
exception safe (there are still many non-safe pointers around), this made it possible to add a regtest that
actually tests erroneous cmd strings and erroneous inputs.
• Due to the required c++11 support, travis-ci test on Ubuntu Precise has been removed.
• gettimeofdate and gettime have been replaced with portable chrono classes introduced in c++11.
• C++ exceptions are enabled by default.
• A large number of loops have been changed to use the auto keyword in order to improve code readability.
• Stack trace is not written upon error anymore, unless environment variable PLUMED_STACK_TRACE is set
at runtime.
• Fixed a potential bug using single precision system BLAS on a mac (notice that currently plumed only uses
double precision, so it is harmless).
• Added --enable-rpath option for autoconf (off by default).
• Files related to changelog are now stored as .md files. This makes it possible to navigate them from github.
• configure.ac has been simplified and improved in order to more easily probe C++ libraries.
• added plumed_custom_skip function to regtests in order to skip specific tests based on specific conditions (e.g. OS).
• environment variable LDSO has been renamed to LDSHARED, which is standard in the python community.
• a libplumedWrapper.a library is installed as well, that is used in --runtime patching.
• pkgconfig files are installed.
• plumed config makefile_conf can be used to retrieve Makefile.conf file a posteriori.
• Store MPIEXEC variable at configure time and use it later for running regtests. Notice that in case MPIEXEC
is not specified regtests will be run using the command stored in env var PLUMED_MPIRUN or, if this is also
not defined, using mpirun.
• Added canonical Makefile targets check and installcheck. Notice that check runs checks with noninstalled plumed whereas installcheck uses the installed one, including its correct program name if it
was personalized (e.g. with suffixes). Notice that this modifies the previously available check target.
Version 2.4.1 (Mar 2, 2018)
For users:
• Fixed an important bug affecting RMSD calculations with compilers supporting OpenMP 4 (e.g.: intel compiler). Notice that this bug might potentially affect not only RMSD variable, but also PATHMSD variables
using RMSD, FIT_TO_TEMPLATE, PCAVARS, and possibly other variables based on RMSD calculations
and optimal alignments (see #343). Results might depend on the exact architecture and on how aggressive
is the compiler. The bug is a consequence of some erroneous SIMD directives introduced in 2.4.0, so it does
not affect PLUMED 2.3.x.
• Resolved a problem with CS2BACKBONE and glycine atom names.
• Module VES: Fixed a bug with basis functions that have a constant function different from 1 (e.g. scaled
version of the Legendre basis functions, BF_LEGENDRE) that was causing a time-dependent shift in the
bias potential.
Generated by Doxygen
2.5 Version 2.4
29
• Module VES: In optimizers (OPT_AVERAGED_SGD and OPT_DUMMY) the output of quantities related to
the instantaneous gradients are now off by default as these quantities are generally not useful for normal
users, their output can instead by re-enabled by using the MONITOR_INSTANTANEOUS_GRADIENT keyword. Also added an keyword MONITOR_AVERAGE_GRADIENT that allows to monitor the averaged gradient and output quantities related to it.
• RMSD variable and other collective variables using reference PDB files now crash when zero weights are
passed (see #247).
• Using COM with driver without passing masses now triggers an error instead of reporting NaNs (see #251).
For developers:
• plumed patch -p command can be used twice without triggering an error. This will allow e.g. building
again on MacPorts in cases where the build was interrupted. Notice that this only works for patches without
special after/before patch/revert functions.
Version 2.4.2 (Jul 2, 2018)
For users:
• All fixes done in version 2.3.6. Notice that #363 in version 2.4 also applies to pathtools.
• Additional residue names (without the prefix D) are now supported by MOLINFO for DNA. See #367.
• Solved an important bug appearing in NAMD interface. Notice that the bug was a regression introduced in
2.4.0. As consequence, versions <= 2.3 and versions >=2.4.2 are expected to work correctly. See #254.
• GROMACS patch for gromacs-2018.1.
• Using VIM syntax file now highlights __FILL__ strings.
• METAD and PBMETAD give a warning when one restarts a simulation and the old hills file is not found. See
#366.
For developers:
• LDSHARED is now correctly taken into account when launching ./configure.
• Fixed installation with --disable-shared.
• Cppcheck upgraded to 1.84.
Version 2.4.3 (Oct 5, 2018)
For users:
• All fixes done in version 2.3.7.
• Module VES: Fixed a bug in TD_GRID for 2D grids where the grid spacing is not the same for both dimensions.
• GROMACS patch for gromacs-2018.3.
Generated by Doxygen
30
Change Log
Version 2.4.4 (Dec 19, 2018)
For users:
• Fixed some performances regression issue with OpenMP
• Updated NAMD patches to version 2.12 and 2.13. Old patches have been removed.
• GROMACS patch for gromacs-2018.4.
• Fixed a thread safety issue using forces on HISTOGRAM
• Fixed error message suggesting wrong actions (see #421).
For developers:
• All fixed done in version 2.3.8
• CPPCHECK updated to 1.85
Version 2.4.5 (Apr 1, 2019)
Warning
This branch is not maintained. Users are invited to upgrade to a newer version
For users:
• Fixed an inconsistency in parsing of braces. It is now possible to pass individual options including spaces
(e.g. with FILE={/path with space/file}). Notice that this invalidates syntax such as ATO←MS={1}{2}{3}{4}. See more at #434.
• Fixed simplemd so as to call "runFinalJobs" at the end of the simulation.
• GROMACS patch for gromacs-2016.6.
• GROMACS patch for gromacs-2018.6.
• Added aliases for some actions/options containing dashes (-) in their name. This will improve backward
compatibility when these actions/options will be removed (see #449).
2.6
Version 2.5
Version 2.5 (Dec 19, 2018)
This page contains changes that will end up in 2.5
Changes from version 2.4 which are relevant for users:
• Changes leading to incompatible behavior:
Generated by Doxygen
2.6 Version 2.5
31
– RMSD, MULTI-RMSD, PATHMSD, PROPERTYMAP, PCAVARS, PCARMSD, FIT_TO_TEMPLATE,
DIPOLE, ALPHARMSD, ANTIBETARMSD, and PARABETARMSD now automatically make molecules
whole. In case you do not want them to do it, use NOPBC flag,
– There is some subtle change in the installation layout (see below). There should be no visible effect,
however it is now compulsory to set correctly the LD_LIBRARY_PATH variable for the linux executable
to work correctly. The procedure has been tested well on OSX and Linux, but could give problems on
other platform. Please report possible problems on the mailing list.
– driver now stops correctly when using COMMITTOR. If you want to continue the analysis, use the
NOSTOP flag in COMMITTOR.
– METAD the calculation of the reweighting factor is now activated by CALC_RCT instead of REWEIG←HTING_NGRID and REWEIGHTING_NHILLS, the frequency of update can be set by RCT_USTRIDE,
the default value is 1 and should be OK for most of the cases
– Fixed sign in Cartesian components of PUCKERING with 6 membered rings (thanks to Carol Simoes
and Javi Iglesias).
• New actions:
– COLLECT_FRAMES
– EUCLIDEAN_DISSIMILARITIES
– HBPAMM_MATRIX
– HBPAMM_SH
– LANDMARK_SELECT_FPS
– LANDMARK_SELECT_RANDOM
– LANDMARK_SELECT_STAGED
– LANDMARK_SELECT_STRIDE
– OUTPUT_ANALYSIS_DATA_TO_COLVAR
– OUTPUT_ANALYSIS_DATA_TO_PDB
– OUTPUT_PCA_PROJECTION
– PAMM
– PLUMED
– PRINT_DISSIMILARITY_MATRIX
– PROJECT_ALL_ANALYSIS_DATA
– READ_DISSIMILARITY_MATRIX
– RESELECT_LANDMARKS
– REWEIGHT_WHAM
– SKETCHMAP_CONJGRAD
– SKETCHMAP_POINTWISE
– SKETCHMAP_READ
– SKETCHMAP_SMACOF
– SKETCH_MAP
– SMACOF_MDS
– WHAM_HISTOGRAM
– WHAM_WEIGHTS
• New command line tools:
– completion (used to generate command line completion scripts).
– pdbrenumber (see #371).
• New modules:
Generated by Doxygen
32
Change Log
– A new PIV module has been included, contributed by Silvio Pipolo and Fabio Pietrucci. This module
implements the following collective variable:
* PIV
– A new LOGMFD module has been included, contributed by Tetsuya Morishita. This module implements
the following bias:
* LOGMFD
• Changes in the ISDB module
– CS2BACKBONE is now mpi parallelized in particular with DOSCORE and CAMSHIFT
– SAXS has an additional implementation based on Bessel functions that can be faster for large systems
(new keyword BESSEL)
– SAXS keyword SCEXP has been renamed into SCALEINT
– SAXS includes the MARTINI bead structure factors for Proteins and Nucleic Acids
– SAXS includes a GPU implementation based on ArrayFire (need to be linked at compile time) that can
be activated with GPU
– METAINFERENCE and all related methods has a new keyword REGRES_ZERO to scale data using a
linear scale fit
– CALIBER new bias to perform Maximum Caliber replica-averaged restrained simulations
• Changes in the eABF/DRR module (contributed by Haochuan Chen and Haohao Fu):
– DRR now supports the extended generalized ABF(egABF) method.
– DRR accepts different GRID options for CVs and extended variables.
– The MAXFACTOR option is added in DRR to control the factor of biasing force.
– drr_tool can calculate the divergence of gradients now. (Maybe useful for future pABF)
– Fixed conflicts of output files in multiple replicas.
• Changes in the EDS module:
– EDS implements Levenberg-Marquardt optimization in addition to previous gradient descent.
– EDS no longer automatically increases prefactor for bias parameter updates. This results in more stable
optimization for the cases tested.
– EDS now has a larger default RANGE parameter to go with these other changes.
• Other changes:
– METAD there is a new FLYING_GAUSSIAN keyword to activate the flying gaussian methods by Spiwok
(contributed by Spiwok and Hozzova)
– EXTERNAL can now SCALE the input grid. This allows for more flexibility without modifying the grid
file.
– ALPHABETA can now combine dihedral angles with different coefficients
– INCLUDE can now be used also before setup actions.
– CENTER can now be computed using trigonometric functions (PHASES) to simplify its calculation with
periodic boundary conditions.
– Libmatheval is not used anymore. MATHEVAL (and CUSTOM) are still available but employ an internal
implementation of the lepton library. Functions available in libmatheval and absent in the original lepton
library have been added so as to have backward compatibility. atan2(y,x) function has also been
added. Notice that MATHEVAL (and CUSTOM) switching functions using the lepton library have been
further optimized with respect to PLUMED 2.4. Finally, notice that it is possible to use asmjit to optimize
performance (see Making lepton library faster).
– Implemented bash autocompletion, see Using bash autocompletion.
– MOLINFO now allows selecting atoms from chains with a numeric ID (see #320).
– Removed the patch for GMX 5.1.4
Generated by Doxygen
2.6 Version 2.5
33
– LAMMPS patch has been finally removed. Notice that LAMMPS has native support for PLUMED now.
– AMBER patch has been finally removed. Notice that AMBER (sander module) has native support for
PLUMED starting from version 15.
– RMSD calculation has been optimized. This should positively affect the performances of CVs where
many RMSD values are computed on small groups of atoms, such as secondary structure variables.
– In METAD, when using a bias factor equal to one (no bias) the rct component is set to zero rather
than to one.
– New shortcuts are available for selecting atoms: @allatoms and @mdatoms (see Specifying Atoms).
– When using MOLINFO, also the following shortcuts are available for selecting atoms: @nucleic,
@protein, @water, @ions, @hydrogens, @nonhydrogens.
– When using MOLINFO, individual atoms can be chosen also from water molecules (e.g. @OW-100).
– Additional switching function COSINUS contributed by Michael King
– added API to set the number of used openMP threads from the linked code, updated gromacs 2018.3
patch to use it
Changes from version 2.4 which are relevant for developers:
• Code has been cleanup up replacing a number of pointers with std::unique_ptr. All delete statements in the core parts of the code have been eliminated.
• Exceptions cannot be disabled (--disable-cxx-exceptions option has been removed from
./configure).
• Every exception thrown in PLUMED now also writes its message on PLUMED log.
• Runtime loader in Plumed.c now works also when linked without -rdynamic (that is, its names are not
exported). Notice that all the combinations are expected to work, that is: Plumed.c from <=2.4 or >=2.5
combined with libplumedKernel from <=2.4 or >=2.5. In order to achieve this the following changes are
implemented:
– libplumedKernel does not depend anymore on Plumed.c. This allows loading it even in cases where
names in the loader are not visible. The relevant function needed to be compatible with Plumed.c
<=2.4 are found using dlsym.
– Plumed.c does not need anymore libplumedKernel to register itself, but rather searches the relevant
functions using dlsym. In addition, if it is not able to load libplumedKernel since the latter is
<=2.4 and needs Plumed.c to be visible, it just uses as a fallback libplumed, which should load
properly.
• In addition to the capability mentioned above, the MD-code interface has been significantly improved and
allows for:
– Translation of exception (allowing to mix PLUMED and an MD-code linked against a different C++ library).
– Possibility to choose the path to the PLUMED kernel while instantiating a Plumed object. See the
developer documentation for more information.
• The installation layout of shared libraries has been modified. In particular, both libplumed.so and
plumed links to libplumedKernel.so. This reduces considerably the size of the installed package.
In addition, it allows using two-level namespace on OSX. Notice that this implies that on Linux one should
always set the LD_LIBRARY_PATH flag to have a working executable.
• A smaller number of header files is installed. In particular, all the files that were historically generated in
subdirectories (such as ‘plumed/core/tools/Vector.h’, just including plumed/tools/Vector.h) are not
installed and the related include statements are fixed. This makes the installed package smaller.
• List of preferred compilers (used when CXX or CC are not set) has been changed. On OSX, ./configure
will try clang++/clang as first choices.
Generated by Doxygen
34
Change Log
• Added --enable-static-archive to ./configure to build a libplumed.a static library (yes
by default).
• Stop setting DYLD_LIBRARY_PATH in sourceme.sh and in modulefile. Notice that as of PLUMED
v2.3.3 it should not be needed.
• Coverage scan is not anymore contained in developer manual. It can be found in a separate repository
github.com/coverage-branch (see #348). In addition, coverage for third-party libraries included in
PLUMED is reported as well.
• It is not possible anymore to use make install prefix=/path. Prefix can only be changed during
./configure (see #332).
• Exception class has been rewritten to allow more extensive messages. Now also function name is shown.
• On linux, library is linked with -Bsymbolic.
• When launching plumed, flags --no-mpi and --mpi can appear multiple times. The last appearence is
the effective one.
• Internal BLAS and LAPACK libraries updated to gromacs 2018.
• Choosing ./configure --prefix=$PWD does not lead anymore to deletion of all header files.
• A copy of plumed-runtime is installed in prefix/lib/plumed and can be used for testing.
• Absolute/relative soname/install_name can be configured on linux/OSX. This feature is only for testing, the
default choice is the typical one used on the respective operating system.
• On OSX, plumed and libplumed.dylib will find libplumedKernel.dylib using @loader_←path.
• Using CXX compiler to link the main program.
• plumed can be compiled with ArrayFire to enable for gpu code. SAXS collective variable is available as part
of the isdb module to provide an example of a gpu implementation for a CV
Version 2.5.1 (Apr 1, 2019)
For users:
• in SAXS the keyword ADDEXP is removed. Furthemore, SAXS intensities are automatically normalised for
I(0)=1, in case experimental data are provided, the intensity is rescaled with the intensity of the lowest q
provided. As a consequence SCALEINT is only needed for additional adjustments.
• gromacs patch updated to gromacs 2018.5
• Fixed a bug in gromacs patch that was resulting in incorrect number of threads (0) set when not explicitly
using -ntomp on the command line or setting OMP_NUM_THREADS (see #446). To apply this fix you need
to re-patch gromacs. Notice that setting the number of threads to zero might lead to inconsistent results when
using secondary structure variables or other multicolvars.
• Fixed PLUMED so that when zero threads are selected from gromacs (see previous fix) the number of used
threads is set to 1. This fix allows to use a GROMACS executable patched with PLUMED 2.5.0 and linked
at runtime with PLUMED 2.5.1 without introducing errors. However, re-patching is preferred since it selectes
the correct number of threads.
• Python wrappers:
– Fixed building of python interface on MacOS Mojave (see #445, thanks to Omar Valsson).
– Numpy is not required anymore at build time (though it is required at runtime for our tests).
– Raw python arrays can be passed as an alternative to Numpy ndarrays.
Generated by Doxygen
2.7 Unreleased changes
35
Version 2.5.2 ()
For users:
• New shortcuts are available for selecting protein atoms: @chi2-#, @chi3-#,@chi4-# and @chi5-#
• Fixed performance of CUSTOM when having zero derivatives with respect to some arguments.
2.7
Unreleased changes
This page contains changes that will end up in 2.6
• Asmjit is now embedded into PLUMED. In order to enable it, it is sufficient to configure with
--enable-asmjit. See this page.
• New contributed modules:
– A new Maze module by Jakub Rydzewski
* MAZE_LOSS
* MAZE_MEMETIC_SAMPLING
* MAZE_RANDOM_ACCELERATION_MD
* MAZE_RANDOM_WALK
* MAZE_SIMULATED_ANNEALING
* MAZE_STEERED_MD
* MAZE_OPTIMIZER_BIAS
• Changes in the VES module
– new VES_DELTA_F bias
Generated by Doxygen
36
Change Log
Generated by Doxygen
Chapter 3
Installation
In this page you can learn how to configure, compile, and install PLUMED. For those of you who are impatient, the
following might do the job:
>
>
>
>
./configure --prefix=/usr/local
make -j 4
make doc # this is optional and requires proper doxygen version installed
make install
Notice that make install is not strictly necessary as plumed can be used from the compilation directory. This
is very useful so as to quickly test the implementation of new features. However, we strongly recommend to perform
a full install.
Once the above is completed the plumed executable should be in your execution path and you will be able to use
PLUMED to analyze existing trajectories or play with the Lennard-Jones code that is included. However, because
PLUMED is mostly used to bias on the fly simulations performed with serious molecular dynamics packages, you
can find instructions about how to patch your favorite MD code so that it can be combined with PLUMED below.
Again, if you are impatient, something like this will do the job:
> cd /md/root/dir
> plumed patch -p
Then compile your MD code. For some MD codes these instructions are insufficient. It is thus recommended that
you read the instructions at the end of this page. Notice that MD codes could in principle be "PLUMED ready" in
their official distribution. If your favorite MD code is available "PLUMED ready" you will have to compile PLUMED
first, then (optionally) install it, then check the MD codes' manual to discover how to link it.
3.1
Supported compilers
As of PLUMED 2.4, we require a compiler that supports C++11. The following compilers (or later versions) should
be sufficient:
• gcc 4.8.1
• clang 3.3
• intel 15
Notice that the ./configure script verifies that your compiler supports C++11. Some compilers do not declare
full support, but implement anyway a number of C++11 features sufficient to compile PLUMED (this is the case
for instance of intel 15 compiler). In case you see a warning about C++11 support during ./configure please
make sure that PLUMED compiles correctly and, if possible, execute the regtests (using make regtest). Notice
that we regularly test a number of compilers on travis-ci, and at least those compilers are guaranteed to be able to
compile PLUMED correctly.
38
3.2
Installation
Configuring PLUMED
The ./configure command just generates a Makefile.conf file and a sourceme.sh file. In PLUMED 2.0 these
files were prepared and stored in the directory configurations/. The new ones generated by ./configure are similar
to the old ones but are not completely compatible. In particular, some of the -D options have been changed in
version 2.2, and several new variables so as to specify the installation directories have been added. For this reason,
you now should run ./configure again. Anyway, it should be easy to enforce a similar setup with autoconf by
passing the proper arguments on the command line. If you have problems on your architecture, please report them
to the mailing list.
Useful command line options for ./configure can be found by typing
> ./configure --help
PLUMED is made up of modules. Some of them are on by default, some others aren't. Since version 2.3, the activation of modules should be made during configuration using the --enable-modules option (see List of modules).
Notice that some functionalities of PLUMED depend on external libraries which are looked for by configure. You can
typically avoid looking for a library using the "disable" syntax, e.g.
> ./configure --disable-mpi --disable-xdrfile
Notice that when MPI search is enabled (by default) compilers such as "mpic++" and "mpicxx" are searched for
first. On the other hand, if MPI search is disabled ("./configure --disable-mpi") non-mpi compilers are searched for.
Notice that only a few of the possible compiler name are searched. Thus, compilers such as "g++-mp-4.8" should
be explicitly requested with the CXX option.
You can better control which compiler is used by setting the variables CXX and CC. E.g., to use Intel compilers use
the following command:
> ./configure CXX=icpc CC=icc
Notice that we are using icpc in this example, which is not an MPI compiler as a result MPI will not be enabled.
Also consider that this is different with respect to what some other configure script does in that variables such as
MPICXX are completely ignored here. In case you work on a machine where CXX is set to a serial compiler and
MPICXX to a MPI compiler, to compile with MPI you should use
> ./configure CXX="$MPICXX"
Warning
This procedure could be somehow confusing since many other programs behave in a different way. The flag
--enable-mpi is perfectly valid but is not needed here. Autoconf will check if a code containing MPI calls
can be compiled, and if so it will enable it. --disable-mpi could be used if you are using a compiler that
supports MPI but you don't want PLUMED to be compiled with MPI support. Thus the correct way to enable
MPI is to pass to ./configure the name of a C++ compiler that implements MPI using the CXX option. In this
way, MPI library is treated similarly to all the other libraries that PLUMED tries to link by default.
To tune the compilation options you can use the CXXFLAGS variable:
> ./configure CXXFLAGS=-O3
If you are implementing new functionality and want to build with debug flags in place so as to do some checking you
can use
Generated by Doxygen
3.2 Configuring PLUMED
39
> ./configure --enable-debug
This will perform some extra check during execution (possibly slowing down PLUMED) and write full symbol tables
in the executable (making the final executable much larger).
The main goal of the automatic configure is to find the libraries. When they are stored in unconventional places it
is thus sensible to tell autoconf where to look! To do this there are some environment variable that can be used to
instruct the linker which directories it should search for libraries inside. These variables are compiler dependent, but
could have been set by the system administrator so that libraries are found without any extra flag. Our suggested
procedure is to first try to configure without any additional flags and to then check the log so as to see whether or
not the libraries were properly detected.
If a library is not found during configuration, you can try to use options to modify the search path. For example if
your xdrfile libraries is in /opt/local (this is where MacPorts put it) and configure is not able to find it you can try
> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include
Notice that PLUMED will first try to link a routine from say xdrfile without any additional flag, and then in case of
failure will retry adding "-lxdrfile" to the LIBS options. If also this does not work, the xdrfile library will be disabled
and some features will not be available. This procedure allows you to use libraries with custom names. So, if your
xdrfile library is called /opt/local/lib/libmyxdrfile.so you can link it with
> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include LIBS=-lmyxdrfile
In this example, the linker will directly try to link /opt/local/lib/libmyxdrfile.so. This rule is true for
all the libraries, so that you will always be able to link a specific version of a library by specifying it using the LIBS
variable.
Since version 2.3.2, the search for the library functions passing to the linker a flag with the standard library name
(in the xdrfile example, it would be -lxdrfile) can be skipped by using the option --disable-libsearch.
Notice that in this manner only libraries that are explicitly passed using the LIBS option will be linked. For instance
> ./configure --disable-libsearch LIBS=-lxdrfile
will make sure that only xdrfile is linked and, for instance, BLAS and LAPACK libraries are not. This might be useful
when installing PLUMED within package managers such as MacPorts to make sure that only desired libraries are
linked and thus to avoid to introduce spurious dependencies. The only exception to this rule is -ldl, which is
anyway a system library on Linux.
Warning
On OSX it is common practice to hard code the full path to libraries in the libraries themselves. This means
that, after having linked a shared library, that specific shared library will be searched in the same place (we do
the same for the libplumed.dylib library, which has an install name hard coded). On the other hand, on
Linux it is common practice not to hard code the full path. This means that if you use the LDFLAGS option to
specify the path to the libraries you want to link to PLUMED (e.g. ./configure LDFLAGS="-L/path")
these libraries might not be found later. The visible symptom is that src/lib/plumed-shared will not
be linked correctly. Although the file 'src/lib/plumed-shared' is not necessary, being able to produce it means
that it will be possible to link PLUMED dynamically with MD codes later. The easiest solution is to hard code
the library search path in this way:
> ./configure LDFLAGS="-L/path -Wl,-rpath,/path"
Notice that as of PLUMED v2.4 it is possible to use the configure option --enable-rpath to automatically
hard code the path defined in LIBRARY_PATH:
> ./configure LIBRARY_PATH=/path --enable-rpath
In this way, the search path used at link time (LIBRARY_PATH) and the one saved in the libplumed.←so library will be consistent by construction. In a typical environment configured using module framework
(http://modules.sourceforge.net), LIBRARY_PATH will be a variable containing the path to all
the modules loaded at compilation time.
Generated by Doxygen
40
Installation
PLUMED needs BLAS and LAPACK. These are treated slightly different from other libraries. The search is done in
the usual way (i.e., first look for them without any link flag, then add "-lblas" and "-llapack", respectively). As such if
you want to use a specific version of BLAS or LAPACK you can make them available to configure by using
> ./configure LDFLAGS=-L/path/to/blas/lib LIBS=-lnameoflib
If the functions of these libraries are not found, the compiler looks for a version with a final underscore added.
Finally, since BLAS and LAPACK are compulsory in PLUMED, you can use a internal version of these libraries
that comes as part of PLUMED. If all else fails the internal version of BLAS and LAPACK are the ones that will be
used by PLUMED. If you wish to disable any search for external libraries (e.g. because the system libraries have
problems) this can be done with
> ./configure --disable-external-blas
Notice that you can also disable external LAPACK only, that is use internal LAPACK with external BLAS using
> ./configure --disable-external-lapack
Since typically it is the BLAS library that can be heavily optimized, this configuration should not provide significant
slowing down and could be used on systems where native LAPACK libraries have problems.
As a final resort, you can also edit the resulting Makefile.conf file. Notable variables in this file include:
• DYNAMIC_LIB : these are the libraries needed to compile the PLUMED library (e.g. -L/path/to/xdrfile -lxdrfile
etc). Notice that for the PLUMED shared library to be compiled properly these should be dynamic libraries.
Also notice that PLUMED preferentially requires BLAS and LAPACK library; see BLAS and LAPACK for
further info. Notice that the variables that you supply with configure LIBS=something will end up in
this variable. This is a bit misleading but is required to keep the configuration files compatible with PLUMED
2.0.
• LIBS : these are the libraries needed when patching an MD code; typically only "-ldl" (needed to have functions
for dynamic loading).
• CPPFLAGS : add here definition needed to enable specific optional functions; e.g. use -D__PLUMED_HA←S_XDRFILE to enable the xdrfile library
• SOEXT : this gives the extension for shared libraries in your system, typically "so" on UNIX, "dylib" on mac; If
your system does not support dynamic libraries or, for some other reason, you would like a static executable
you can just set this variable to a blank ("SOEXT=").
3.2.1
BLAS and LAPACK
We tried to keep PLUMED as independent as possible from external libraries and as such those features that require
external libraries (e.g. Matheval) are optional. However, to have a properly working version of plumed PLUMED
you need BLAS and LAPACK libraries. We would strongly recommend you download these libraries and install
them separately so as to have the most efficient possible implementations of the functions contained within them.
However, if you cannot install BLAS and LAPACK, you can use the internal ones. Since version 2.1, PLUMED uses
a configure script to detect libraries. In case system LAPACK or BLAS are not found on your system, PLUMED will
use the internal replacement.
We have had a number of emails (and have struggled ourselves) with ensuring that PLUMED can link BLAS and
LAPACK. The following describes some of the pitfalls that you can fall into and a set of sensible steps by which you
can check whether or not you have set up the configuration correctly.
Notice first of all that the DYNAMIC_LIB variable in the Makefile.conf should contain the flag necessary to load the
BLAS and LAPACK libraries. Typically this will be -llapack -lblas, in some case followed by -lgfortran. Full path
specification with -L may be necessary and on some machines the BLAS and LAPACK libraries may not be called
-llapack and -lblas. Everything will depend on your system configuration.
Some simple to fix further problems include:
Generated by Doxygen
3.3 Compiling PLUMED
41
• If the linker complains and suggests recompiling LAPACK with -fPIC, it means that you have static LAPACK
libraries. Either install dynamic LAPACK libraries or switch to static compilation of PLUMED by stopping to
set the SOEXT variable in the configuration file.
• If the linker complains about other missing functions (typically starting with "for_" prefix) then you should also
link some Fortran libraries. PLUMED is written in C++ and often C++ linkers do not include Fortran libraries
by default. These libraries are required for LAPACK and BLAS to work. Please check the documentation of
your compiler.
• If the linker complains that dsyevr_ cannot be found, try adding -DF77_NO_UNDERSCORE to CPPFLAGS
Notice that "./configure" should automatically try this solution.
3.2.2
VMD trajectory plugins
If you configure PLUMED with the VMD plugins you will be able to read many more trajectory formats. To this aim,
you need to download the SOURCE of VMD, which contains a plugins directory. Adapt build.sh and compile it. At
the end, you should get the molfile plugins compiled as a static library libmolfile_plugin.a. Locate said file
and libmolfile_plugin.h, they should be in a directory called /pathtovmdplugins/ARCH/molfile
(e.g. /pathtovmdplugins/MACOSXX86_64/molfile). Also locate file molfile_plugin.h, which
should be in /pathtovmdplugins/include. Then customize the configure command with something along
the lines of:
./configure LDFLAGS="-L/pathtovmdplugins/ARCH/molfile" CPPFLAGS="-I/pathtovmdplugins/include -I/pathtovmdplugi
Notice that it might be necessary to add to LDFLAGS the path to your TCL interpreter, e.g.
./configure LDFLAGS="-ltcl8.5 -L/mypathtotcl -L/pathtovmdplugins/ARCH/molfile" \
CPPFLAGS="-I/pathtovmdplugins/include -I/pathtovmdplugins/ARCH/molfile"
Then, rebuild plumed.
3.3
Compiling PLUMED
Once configured, PLUMED can be compiled using the following command:
> make -j 4
This will compile the entire code and produce a number of files in the 'src/lib' directory, including the executable
'src/lib/plumed'. When shared libraries are enabled, a shared libraries called 'src/lib/libKernel.so' should also be
present. Notice that the extension could be '.dylib' on a Mac.
In case you want to run PLUMED without installing it (i.e. from the compilation directory), you can use the file
'sourceme.sh' that has been created by the configure script in the main PLUMED directory. This file can be "sourced"
(presently only working for bash shell) if you want to use PLUMED before installing it (i.e. from the compilation
directory). It is a good idea to source it now, so that you can play with the just compiled PLUMED:
> source sourceme.sh
Now a "plumed" executable should be in your path. Try to type
> plumed -h
Generated by Doxygen
42
Installation
Warning
If you are cross compiling, the plumed executable will not work. As a consequence, you won't be able to run
regtests or compile the manual. This is not a problem.
You can also check if PLUMED is correctly compiled by performing our regression tests. Be warned that some of
them fail because of the different numerical accuracy on different machines. As of version 2.4, in order to test the
plumed executable that you just compiled (prior to installing it) you can use the following command
> make check
On the other hand, in order to test the plumed executable that you just installed (see Installing PLUMED) you
should type
> make installcheck
In addition, similarly to previous versions of PLUMED, you can test the plumed executable that is in your current
path with
> cd regtest
> make
You can check the exact version they will use by using the command
> which plumed
Thus, you can easily run the test suite using a different version of PLUMED (maybe an earlier version that you
already installed), just making sure that it can be found in the path. Clearly, if you test a given version of PLUMED
with a test suite from a different version you can expect two possible kinds of innocuous errors:
• If plumed executable is older than the test suite, the tests might fail since they rely on some feature introduced in PLUMED in a newer version.
• If plumed executable is newer than the test suite, the tests might fail since some non-backward compatible
change was made in PLUMED. We try to keep the number of non-backward compatible changes small, but
as you can see in the Change Log there are typically a few of them at every new major release.
Attention
Even though we regularly perform tests on Travis-CI, it is possible that aggressive optimizations or even
architecture dependent features trigger bugs that did not show up on travis. So please always perform regtests
when you install PLUMED.
Notice that the compiled executable, which now sits in 'src/lib/plumed', relies on other resource files present in the
compilation directory. This directory should thus stay in the correct place. One should thus not rename or delete it.
In fact the path to the PLUMED root directory is hard coded in the plumed executable as can be verified using
> plumed info --root
In case you try to use the plumed executable without the compilation directory in place (e.g. you move away the
src/lib/plumed static executable and delete or rename the compilation directory) PLUMED will not work correctly
and will give you an error message
> plumed help
ERROR: I cannot find /xxx/yyy/patches directory
You can force plumed to run anyway by using the option –standalone-executable:
> plumed --standalone-executable help
Many features will not be available if you run in this way. However, this is currently the only way to use the PLUMED
static executable on Windows.
Generated by Doxygen
3.4 Installing PLUMED
3.4
43
Installing PLUMED
It is strongly suggested to install PLUMED in a predefined location. This is done using
> make install
This will allow you to remove the original compilation directory, or to recompile a different PLUMED version in the
same place.
To install PLUMED one should first decide the location:
> ./configure --prefix=$HOME/opt
> make
> make install
As of PLUMED 2.5 you cannot anymore change the location during install. If you didn't specify the --prefix
option during configure PLUMED will be installed in /usr/local. The install command should be executed with root
permissions (e.g. "sudo make install") if you want to install PLUMED on a system directory.
Notice that upon installation PLUMED might need to relink a library. This was always true until version 2.1, but in
version 2.2 libraries should only be relinked if one changes the install prefix during when typing make install.
If root user does not have access to compilers, "sudo -E make install" might solve the issue.
Upon install, the executable is copied to $prefix/bin, libraries to $prefix/lib, include files to $prefix/include, and documentation to $prefix/shared/doc/plumed. Additionally, a directory $prefix/lib/plumed is created containing several
other files, including patch files, object files (for static patches), etc. Notice also that these path can be further
customized using standard autoconf directories (e.g. ./configure --bindir=/usr/bin64).
One should then set the environment properly. We suggest to do it using the module framework (http←://modules.sourceforge.net). An ad hoc generated module file for PLUMED can be found in $prefix/lib/plumed/src/lib/modulefile Just edit it as you wish and put it in your modulefile directory. This will also allow
you to install multiple PLUMED versions on your machine and to switch among them. If you do not want to use
modules, you can still have a look at the modulefile we did so as to know which environment variables should be
set for PLUMED to work correctly.
If the environment is properly configured one should be able to do the following things:
• use the "plumed" executable from the command line. This is also possible before installing.
• link against the PLUMED library using the "-lplumed" flag for the linker. This allows one to use PLUMED
library in general purpose programs
• use the PLUMED internal functionalities (C++ classes) including header files such as "#include
". This is useful as it may be expedient to exploit the PLUMED library in general purpose programs
As a final note, if you want to install several PLUMED versions without using modules then you should provide a
different suffix and/or prefix at configure time:
> ./configure prefix=$HOME/opt --program-suffix=_2.2 --program-prefix=mpi> make install
This will install a plumed executable named "mpi-plumed_2.2". All the other files will be renamed similarly, e.←g. the PLUMED library will be loaded with "-lmpi-plumed_2.2" and the PLUMED header files will be included with
"#include ". Notice that you can also use arbitrary scripts to edit the name of
the executable with the option –program-transform-name=PROGRAM (see autoconf documentation for
more info). These options are useful if you do not want to set up modules, but we believe that using modules as
described above is more flexible.
Generated by Doxygen
44
3.5
Installation
Patching your MD code
A growing number of MD codes can use PLUMED without any modification. If you are using one of these codes,
refer to its manual to know how to activate PLUMED. In case your MD code is not supporting PLUMED already,
you should modify it. We provide scripts to adjust some of the most popular MD codes so as to provide PLUMED
support. At the present times we support patching the following list of codes:
• gromacs-2016-6
• gromacs-2018-6
• gromacs-4-5-7
• namd-2-12
• namd-2-13
• qespresso-5-0-2
• qespresso-6-2
In the section Code specific notes you can find information specific for each MD code.
To patch your MD code, you should have already installed PLUMED properly. This is necessary as you need to
have the command "plumed" in your execution path. As described above this executable will be in your paths if
plumed was installed or if you have run sourceme.sh
Once you have a compiled and working version of plumed, follow these steps to add it to an MD code
• Configure and compile your MD engine (look for the instructions in its documentation).
• Test if the MD code is working properly.
• Go to the root directory for the source code of the MD engine.
• Patch with PLUMED using:
> plumed patch -p
The script will interactively ask which MD engine you are patching.
• Once you have patched recompile the MD code (if dependencies are set up properly in the MD engine, only
modified files will be recompiled)
There are different options available when patching. You can check all of them using
> plumed patch --help
Particularly interesting options include:
• –static just link PLUMED as a collection of object files. This is only suggested if for external reasons you
absolutely need a static executable. Notice that with this setting it is often more complicated to configure
properly the MD code, since all the libraries that PLUMED depends on should be properly specified. The
./configure script does its best in this sense, but sometime it cannot solve the problem. Additionally, this
patching mode has been reported not to work properly on OSX.
Generated by Doxygen
3.6 Cross compiling
45
• –shared (default) allows you to link PLUMED as a shared library. As a result when PLUMED is updated, there
will be no need to recompile the MD code. This is way better than –static since the libraries that PLUMED
depends on should be automatically linked. Notice that if you later remove the directory where PLUMED is
installed also the MD code will not run anymore.
• –runtime allows you to choose the location of the PLUMED library at runtime by setting the variable PLUM←ED_KERNEL. This is probably the most flexible option, and we encourage system administrators to use this
option when installing PLUMED on shared facilities. Indeed, using this setting it will be possible to update
separately the PLUMED library and the MD code, leaving to the user the possibility to combine different
versions at will. We also recommend to use the provided modulefile (see above) to properly set the runtime
environment.
Notice that with PLUMED version <2.5 there was no possibility to link PLUMED as a static library (something like
'libplumed.a'). However, starting with PLUMED 2.5, the ./configure script will try to set up the system so that
a libplumed.a file is produced. Patching an MD code with --static with try to link against this static library.
Creation of the libplumed.a library can be avoided with ./configure --disable-static-archive.
If your MD code is not supported, you may want to implement an interface for it. Refer to the developer manual
.
3.6
Cross compiling
If you are compiling an executable from a different machine, then plumed executable will not be available in the
compilation environment. This means that you won't be able to perform regtests on the machine nor to compile the
manual. You can try to run the regtests on the computing nodes, but this might require some tweak since often
machines where people do cross compiling have architectures with limited capabilities on the compute nodes. Also
notice that many of the plumed options (e.g. patch) are implemented as shell scripts launched from within the
plumed executable. If the compute nodes have some limitation (e.g. they do not allow to fork new processes)
these options will not work. Anyway, the PLUMED library in combination with an MD software should work if both
PLUMED and the MD software have been properly compiled.
Also notice that it will not be possible to use the command plumed patch on the machine where you are
compiling. You should thus use plumed-patch instead of plumed patch (notice that it should be written
as a single word).
Try e.g.:
> plumed-patch --help
This script provides a "shell only" implementation of plumed patch that will skip the launch of the plumed
executable.
Notice that other command line tools will be available in the directory prefix/lib/progname/. If configuring
with default values this would be /usr/local/lib/plumed/plumed-∗. These files are not included in the
execution path (prefix/bin) to avoid clashes, but can be executed also when plumed is cross compiled and the main
plumed executable cannot be launched.
Generated by Doxygen
46
3.7
Installation
Installing PLUMED with MacPorts
If you are using a Mac, notice that you can take advantage of a MacPorts package. Installing a working plumed
should be as easy as:
• Install MacPorts
• Type sudo port install plumed
Notice that plumed comes with many variants that can be inspected with the command
> sudo port info plumed
Plumed uses variants to support different compilers. For instance, you can install plumed with mpich using
> sudo port install plumed +mpich
Using more recent clang instead of native compilers is recommended so as to take advantage of openMP
> sudo port install plumed +mpich +clang50
Notice that support for c++11 with gcc compilers is someway problematic within MacPorts due to impossibility to
use the system c++ library. For this reason, only clang compilers are supported (see also this discussion).
Variants can be also used to compile with debug flags (+debug), to pick a linear algebra library (e.g. +openblas)
and to enable all optional modules (+allmodules). Notice that the default variant installed with sudo port
install plumed is shipped as a compiled binary, which is significantly faster to install.
In addition, we provide a developer version (typically: a later version not yet considered as stable) under the subport
plumed-devel that can be installed with
> sudo port install plumed-devel
plumed-devel also supports the same variants as plumed in order to customize the compilation.
plumed-devel and plumed cannot be installed at the same time.
It is also possible to install a plumed-patched version of gromacs. For instance, you can use the following command
to install gromacs patched with plumed with clang-5.0 compiler and mpich:
> sudo port install plumed +mpich +clang50
> sudo port install gromacs-plumed +mpich +clang50
In case you want to combine gromacs with the unstable version of plumed, use this instead:
> sudo port install plumed-devel +mpich +clang50
> sudo port install gromacs-plumed +mpich +clang50
Notice that gromacs should be compiled using the same compiler variant as plumed (in this example +mpich
+clang50). In case this is not true, compilation will fail.
Also notice that gromacs is patched with plumed in runtime mode but that the path of libplumedKernel.dylib in the
MacPorts tree is hard coded. As a consequence:
• If gromacs is run with PLUMED_KERNEL environment variable unset (or set to empty), then the MacPorts
plumed is used.
• If gromacs is run with PLUMED_KERNEL environment variable pointing to another instance of the plumed
library, the other instance is used.
This is especially useful if you are developing PLUMED since you will be able to install gromacs once for all and
combine it with your working version of PLUMED.
Generated by Doxygen
3.8 Installing PLUMED on a cluster
3.8
47
Installing PLUMED on a cluster
If you are installing PLUMED on a cluster and you want several users to take advantage of it consider the following
suggestions.
First of all, we highly recommend using the module file that PLUMED provides to set up the environment. Just edit
it as necessary to make it suitable for your environment.
Notice that PLUMED can take advantage of many additional features if specific libraries are available upon compiling
it. If someone uses gromacs, install libxdrfile first and check if PLUMED ./configure is detecting it. PLUMED
will be able to write trr/xtc file, simplifying analysis.
Try to patch all MD codes with the --runtime option. This will allow independent update of PLUMED and MD
codes. Users will be able to combine any of the installed gromacs/amber/etc versions with any of the installed
PLUMED versions. Notice that it is sometime claimed that statically linked codes are faster. In our experience, this
is not true. In case you absolutely need a static executable, be ready to face non trivial linking issues. PLUMED
is written in C++, thus required the appropriate C++ library to be linked, and might require additional libraries (e.g.
libxdrfile).
Sometime we make small fixes on the patches. For this reason, keep track of which version of PLUMED you used to
patch each of the MD code. Perhaps you can call the MD code modules with names such as gromacs/4.6.7p1,
gromacs/4.6.7p2 and write somewhere in the module file which version of PLUMED you used. Alternatively,
call them something like gromacs/4.6.7p2.2.0. In this way, when we report a bug on the mailing list, users
will know if the version they are using is affected by it.
Usually it is not necessary to install both a MPI and a non-MPI PLUMED version. PLUMED library only calls MPI
functions when the MD code is compiled with MPI. PLUMED executable calls MPI functions only when it is invoked
without --no-mpi. In many machines it is thus sufficient to run the plumed executable on the login node as
> plumed --no-mpi
even though PLUMED was compiled with MPI and the login node does not support MPI. The only case where you
might need two different PLUMED installation for compute and login node is when you are cross compiling.
PLUMED needs to be well optimized to run efficiently. If you need a single PLUMED binary to run efficiency on
machines with different levels of hardware (e.g.: some of your workstations support AVX and some do not), with
intel compiler you can use something like
./configure CXX=mpicxx CXXFLAGS="-O3 -axSSE2,AVX"
It will take more time to compile but it will allow you to use a single module. Otherwise, you should install two
PLUMED version with different optimization levels.
Using modules, it is not necessary to make the PLUMED module explicitly dependent on the used library. Imagine a
scenario where you first installed a module libxdrfile, then load it while you compile PLUMED. If you provide
the following option to configure --enable-rpath, the PLUMED executable and library will remember where
libxdrfile is, without the need to load libxdrfile module at runtime. Notice that this trick often does not work for
fundamental libraries such as C++ and MPI library. As a consequence, usually the PLUMED module should load
the compiler and MPI modules.
Attention
In case you found out how to compile PLUMED on some fancy architecture please share your tricks! You can
either post it in your blog, send it to the mailing list, or ask as to update this paragraph in the manual, we will
be happy to do so.
Generated by Doxygen
48
3.9
Installation
Installing Python wrappers
As of PLUMED 2.5 it is possible to use the PLUMED library through Python wrappers. Notice that this is not
something for end users but rather for developers. The interface is very similar to the one used in MD codes linked
with PLUMED.
There are two ways to install Python wrappers.
3.9.1
Installing Python wrappers within PLUMED
If ./configure finds a python executable that also has the cython module available, Python wrappers will
be installed within /prefix/lib/plumed/python. In order to access them, you should add this directory to
the environment variable PYTHONPATH. Notice that if your python interpreter has a different name you might have
to pass it to ./configure with PYTHON_BIN=python3.6. The whole thing would then be:
./configure PYTHON_BIN=python3.6 --prefix=$HOME/opt
make && make install
export PYTHONPATH="$HOME/opt/lib/plumed/python:$PYTHONPATH"
python3.6
>>> import plumed
Notice that in this manner you will have to commit to a specific python version before installing PLUMED.
3.9.2
Installing Python wrappers outside PLUMED
If you use multiple python versions, you might find it easier to install the Python wrappers separately from PLUMED.
The simplest way is to do it with pip:
pip3.6 install --user plumed
Here the --user flag allows you to install the packages on your home. Notice that you don't even need to download
PLUMED in order to install the wrappers, but you will need PLUMED in order to use them. You can tell the wrappers
where PLUMED is by setting the PLUMED_KERNEL environment variable:
export PLUMED_KERNEL=$HOME/opt/lib/libplumedKernel.so
python3.6
>>> import plumed
Notice that by installing the wrappers in this manner you will download those that are packaged on Pypi. If you
want to install using pip the development version of the wrappers you should download the PLUMED repository and
use the following commands:
pip3.6 install --user cython # cython is required in this case
cd plumed2/python
make pip
pip3.6 install --user .
If you want to install the development version it is recommended to use a virtualenv so that it will not interfere with
the released packages.
Generated by Doxygen
3.10 Other hints
3.10
49
Other hints
We here collect a list of suggestions that might be useful on particular machines.
• On Blue Gene Q (likely on AIX) the prelinking made with ld -r is not working properly. There is no easy
way to detect this at configure time. If during make you receive an error in the form
ld: TOC section size exceeds 64k
please configure plumed again with the following flag
./configure --disable-ld-r
• On Cray machines, you might have to set the following environment variable before configuring and building
both PLUMED and the MD code that you want to patch with PLUMED (kindly reported by Marco De La
Pierre):
export CRAYPE_LINK_TYPE=dynamic
• Intel MPI seems to require the flags -lmpi_mt -mt_mpi for compiling and linking and the flag -DMP←ICH_IGNORE_CXX_SEEK for compiling (kindly reported by Abhishek Acharya). You might want to try to
configure using
./configure LDFLAGS=-lmpi_mt CXXFLAGS="-DMPICH_IGNORE_CXX_SEEK -mt_mpi" STATIC_LIBS=-mt_mpi
Adding libraries to STATIC_LIBS uses them for all the linking steps, whereas those in LIBS are only used
when linking the PLUMED kernel library. See more at this thread.
3.11
Code specific notes
Here you can find instructions that are specific for patching each of the supported MD codes. Notice that MD codes
with native PLUMED support are not listed here.
• gromacs-2016.6
• gromacs-2018.6
• gromacs-4.5.7
• namd-2.12
• namd-2.13
• qespresso-5.0.2
• qespresso-6.2
3.11.1
gromacs-2016.6
PLUMED can be incorporated into gromacs using the standard patching procedure. Patching must be done in the
gromacs root directory before the cmake command is invoked.
On clusters you may want to patch gromacs using the static version of plumed, in this case building gromacs can
result in multiple errors. One possible solution is to configure gromacs with these additional options:
cmake -DBUILD_SHARED_LIBS=OFF -DGMX_PREFER_STATIC_LIBS=ON
To enable PLUMED in a gromacs simulation one should use mdrun with an extra -plumed flag. The flag can be
used to specify the name of the PLUMED input file, e.g.:
gmx mdrun -plumed plumed.dat
For more information on gromacs you should visit http://www.gromacs.org
Generated by Doxygen
50
3.11.2
Installation
gromacs-2018.6
PLUMED can be incorporated into gromacs using the standard patching procedure. Patching must be done in the
gromacs root directory before the cmake command is invoked.
On clusters you may want to patch gromacs using the static version of plumed, in this case building gromacs can
result in multiple errors. One possible solution is to configure gromacs with these additional options:
cmake -DBUILD_SHARED_LIBS=OFF -DGMX_PREFER_STATIC_LIBS=ON
To enable PLUMED in a gromacs simulation one should use mdrun with an extra -plumed flag. The flag can be
used to specify the name of the PLUMED input file, e.g.:
gmx mdrun -plumed plumed.dat
For more information on gromacs you should visit http://www.gromacs.org
3.11.3
gromacs-4.5.7
PLUMED can be incorporated into gromacs using the standard patching procedure. Patching must be done in the
gromacs source directory after gromacs has been configured but before gromacs is compiled. Gromacs should be
configured with ./configure (not cmake).
To enable PLUMED in a gromacs simulation one should use mdrun with an extra -plumed flag. The flag can be
used to specify the name of the PLUMED input file, e.g.:
mdrun -plumed plumed.dat
For more information on gromacs you should visit http://www.gromacs.org
3.11.4
namd-2.12
To enable PLUMED in a NAMD simulation one should add the following lines in the NAMD configuration file (often
named as xxx.namd or xxx.conf) and run the plumed-patched version of NAMD with it:
plumed on
plumedfile plumed.dat
The first line tells NAMD to run with PLUMED and the second line specifies the PLUMED input file.
Bug NAMD does not currently take into account virial contributions from PLUMED. Please use constant volume
simulations only.
For more information on NAMD you should visit http://www.ks.uiuc.edu/Research/namd/
Generated by Doxygen
3.11 Code specific notes
3.11.5
51
namd-2.13
To enable PLUMED in a NAMD simulation one should add the following lines in the NAMD configuration file (often
named as xxx.namd or xxx.conf) and run the plumed-patched version of NAMD with it:
plumed on
plumedfile plumed.dat
The first line tells NAMD to run with PLUMED and the second line specifies the PLUMED input file.
Bug NAMD does not currently take into account virial contributions from PLUMED. Please use constant volume
simulations only.
For more information on NAMD you should visit http://www.ks.uiuc.edu/Research/namd/
3.11.6
qespresso-5.0.2
For more information on Quantum Espresso you should visit http://www.quantum-espresso.org
3.11.7
qespresso-6.2
For more information on Quantum Espresso you should visit http://www.quantum-espresso.org This
patch was kindly provided by Ralf Meyer, email: meyer.ralf(at)yahoo.com
Generated by Doxygen
52
Installation
Generated by Doxygen
Chapter 4
Getting Started
To run PLUMED you need to provide one input file. In this file you specify what it is that PLUMED should do during
the course of the run. Typically this will involve calculating one or more collective variables, perhaps calculating
a function of these CVs and then doing some analysis of values of your collective variables/functions or running
some free energy method. A very brief introduction to the syntax used in the PLUMED input file is provided in this
10-minute video .
Within this input file every line is an instruction for PLUMED to perform some particular action. This could be the
calculation of a colvar, an occasional analysis of the trajectory or a biasing of the dynamics. The first word in
these lines specify what particular action is to be performed. This is then followed by a number of keywords which
provide PLUMED with more details as to how the action is to be performed. These keywords are either single
words (in which they tell PLUMED to do the calculation in a particular way - for example NOPBC tells PLUMED to
not use the periodic boundary conditions when calculating a particular colvar) or they can be words followed by an
equals sign and a comma separated list with no spaces of numbers or characters (so for example ATOMS=1,2,3,4
tells PLUMED to use atom numbers 1,2,3 and 4 in the calculation of a particular colvar). The reason why spaces
are not admitted is that PLUMED should be able to understand when the list of atoms ended and a new keyword
should be expected. Space separated lists can be used instead of comma separated list if the entire list is enclosed
in curly braces (e.g. ATOMS={1 2 3 4}). Please note that you can split commands over multiple lines by using
Continuation lines.
The most important of these keywords is the label keyword as it is only by using these labels that we can pass data
from one action to another. As an example if you do:
BEGIN_PLUMED_FILE
DISTANCE ATOMS=1,2
Then PLUMED will do nothing other than read in your input file. In contrast if you do:
BEGIN_PLUMED_FILE
DISTANCE ATOMS=1,2 LABEL=d1
PRINT ARG=d1 FILE=colvar STRIDE=10
then PLUMED will print out the value of the distance between atoms 1 and 2 every 10 steps to the file colvar as you
have told PLUMED to take the value calculated by the action d1 and to print it. You can use any character string
to label your actions as long as it does not begin with the symbol @. Strings beginning with @ are used by within
PLUMED to reference special, code-generated groups of atoms and to give labels to any Actions for which the user
does not provide a label in the input.
Notice that if a word followed by a column is added at the beginning of the line (e.g. pippo:), PLUMED automatically
removes it and adds an equivalent label (LABEL=pippo). Thus, a completely equivalent result can be obtained with
the following shortcut:
54
Getting Started
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=1,2
PRINT ARG=d1 FILE=colvar STRIDE=10
Also notice that all the actions can be labeled, and that many actions besides normal collective variables can define
one or more value, which can be then referred using the corresponding label.
Actions can be referred also with POSIX regular expressions (see Regular Expressions) if regex library is available
on your system and detected at configure time. You can also add Comments to the input or set up your input over
multiple files and then create a composite input by Including other files.
More information on the input syntax as well as details on the the various trajectory analysis tools that come with
PLUMED are given in:
• Collective Variables tells you about the ways that you can calculate functions of the positions of the atoms.
• Analysis tells you about the various forms of analysis you can run on trajectories using PLUMED.
• Bias tells you about the methods that you can use to bias molecular dynamics simulations with PLUMED.
4.1
Plumed units
By default the PLUMED inputs and outputs quantities in the following units:
• Energy - kJ/mol
• Length - nanometers
• Time - picoseconds
Unlike PLUMED 1 the units used are independent of the MD engine you are using. If you want to change these
units you can do this using the UNITS keyword.
4.2
UNITS
This is part of the setup module
This command sets the internal units for the code.
A new unit can be set by either specifying a conversion factor from the plumed default unit or by using a string
corresponding to one of the defined units given below. This directive MUST appear at the BEGINNING of the
plumed.dat file. The same units must be used throughout the plumed.dat file.
Notice that all input/output will then be made using the specified units. That is: all the input parameters, all the
output files, etc. The only exceptions are file formats for which there is a specific convention concerning the units.
For example, trajectories written in .gro format (with DUMPATOMS) are going to be always in nm.
The following strings can be used to specify units. Note that the strings are case sensitive.
• LENGTH: nm (default), A (for Angstrom), um (for micrometer), Bohr (0.052917721067 nm)
Generated by Doxygen
4.2 UNITS
55
• ENERGY: kj/mol (default), j/mol, kcal/mol (4.184 kj/mol), eV (96.48530749925792 kj/mol), Ha (for Hartree,
2625.499638 kj/mol)
• TIME: ps (default), fs, ns, atomic (2.418884326509e-5 ps)
• MASS: amu (default)
• CHARGE: e (default)
Options
NATURAL
( default=off ) use natural units
LENGTH
the units of lengths. Either specify a conversion factor from the default, nm, or use one of the
defined units, A (for angstroms), um (for micrometer), and Bohr.
ENERGY
the units of energy. Either specify a conversion factor from the default, kj/mol, or use one of the
defined units, j/mol, kcal/mol and Ha (for Hartree)
TIME
the units of time. Either specify a conversion factor from the default, ps, or use one of the defined
units, ns, fs, and atomic
MASS
the units of masses. Specify a conversion factor from the default, amu
CHARGE
the units of charges. Specify a conversion factor from the default, e
Examples
BEGIN_PLUMED_FILE
# this is using Angstrom - kj/mol - fs
UNITS LENGTH=A TIME=fs
# compute distance between atoms 1 and 4
d: DISTANCE ATOMS=1,4
# print time and distance on a COLVAR file
PRINT ARG=d FILE=COLVAR
# dump atoms 1 to 100 on a ’out.gro’ file
DUMPATOMS FILE=out.gro STRIDE=10 ATOMS=1-100
# dump atoms 1 to 100 on a ’out.xyz’ file
DUMPATOMS FILE=out.xyz STRIDE=10 ATOMS=1-100
In the COLVAR file, time and distance will appear in fs and A respectively, irrespective of which units you are using in
the host MD code. The coordinates in the out.gro file will be expressed in nm, since gro files are by convention
written in nm. The coordinates in the out.xyz file will be written in Angstrom since we used the UNITS command
setting Angstrom units. Indeed, within PLUMED xyz files are using internal PLUMED units and not necessarily
Angstrom!
If a number, x, is found instead of a string, the new unit is equal to x times the default units. Using the following
command as first line of the previous example would have lead to an identical result:
BEGIN_PLUMED_FILE
UNITS LENGTH=0.1 TIME=0.001
Generated by Doxygen
56
Getting Started
Generated by Doxygen
Chapter 5
Collective Variables
Chemical systems contain an enormous number atoms, which, in most cases makes it simply impossible for us to
understand anything by monitoring the atom positions directly. Consequently, we introduce Collective variables (C←Vs) that describe the chemical processes we are interested in and monitor these simpler quantities instead. These
CVs are used in many of the methods implemented in PLUMED - there values can be monitored using PRINT,
Functions of them can be calculated or they can be analyzed or biased using the Analysis and Biasing methods
implemented in PLUMED. Before doing any of these things however we first have to tell PLUMED how to calculate
them.
The simplest collective variables that are implemented in PLUMED take in a set of atomic positions and output one
or multiple scalar CV values. Information on these variables is given on the page entitled CV Documentation while
information as to how sets of atoms can be selected can be found in the pages on Groups and Virtual Atoms.
Please be aware that PLUMED contains implementations of many other collective variables but that the input for these variables may be less transparent when it is first encountered. In particular, the page on
Distances from reference configurations describes the various ways that you can calculate the distance from a particular reference configuration. So you will find instructions on how to calculate the RMSD distance from the folded
state of a protein here. Meanwhile, the page on Functions describes the various functions of collective variables
that can be used in the code. This is a very powerful feature of PLUMED as you can use the Functions commands
to calculate any function or combination of the simple collective variables listed on the page CV Documentation.
Lastly the page on MultiColvar describes MultiColvars.
MultiColvars allow you to use many different colvars and allow us to implement all these collective variables without a
large amount of code. For some things (e.g. DISTANCES GROUPA=1 GROUPB=2-100 LESS_THAN={RATIONAL
R_0=3}) there are more computationally efficient options available in plumed (e.g. COORDINATION). However,
MultiColvars are worth investigating as they provide a flexible syntax for many quite-complex CVs.
• Groups and Virtual Atoms
• CV Documentation
• Distances from reference configurations
• Functions
• MultiColvar
• Exploiting contact matrices
58
Collective Variables
5.1
Groups and Virtual Atoms
5.1.1
Specifying Atoms
The vast majority of the CVs implemented in PLUMED are calculated from a list of atom positions. Within PLUMED
atoms are specified using their numerical indices in the molecular dynamics input file.
In PLUMED lists of atoms can be either provided directly inside the definition of each collective variable, or predefined as a GROUP that can be reused multiple times. Lists of atoms can be written as:
• comma separated lists of numbers (GROUP ATOMS=10,11,15,20 LABEL=g1)
• numerical ranges. So GROUP ATOMS=10-20 LABEL=g2 is equivalent to GROUP ATOMS=10,11,12,13,14,15,16,
LABEL=g2
• numerical ranges with a stride. So GROUP ATOMS=10-100:10 LABEL=g3 is equivalent
toGROUP ATOMS=10,20,30,40,50,60,70,80,90,100 LABEL=g3
• atoms ranges with a negative stride. SoGROUP ATOMS=100-10:-10 LABEL=g4 is
equivalent to GROUP ATOMS=100,90,80,70,60,50,40,30,20,10 LABEL=g4
In addition, there are a few shortcuts that can be used:
• @mdatoms indicate all the physical atoms present in the MD engine (e.g.
MS=@mdatoms).
DUMPATOMS ATO←-
• @allatoms indicates all atoms, including those defined only in PLUMED (e.g.
MS=@allatoms).
DUMPATOMS ATO←-
The list of the virtual atoms defined in PLUMED can be obtained by using the command GROUP ATO←-
MS=@allatoms REMOVE=@mdatoms.
Other shortcuts are available if you loaded the structure of the molecule using the MOLINFO command.
All the above methods can be combined just putting one name after the other separated by a comma:
BEGIN_PLUMED_FILE
DUMPATOMS ATOMS=1,2,10-20,40-60:5,100-70:-2 LABEL=g5 FILE=test.xyz
Some collective variable must accept a fixed number of atoms, for example a DISTANCE is calculated using two
atoms only, an ANGLE is calculated using either 3 or 4 atoms and TORSION is calculated using 4 atoms.
Additional material and examples can be also found in the tutorial Belfast tutorial: Analyzing CVs.
5.1.1.1
Molecules
In addition, for certain colvars, pdb files can be read in using the following keywords and used to select ATOMS:
MOLINFO
This command is used to provide information on the molecules that are present in your system.
Generated by Doxygen
5.1 Groups and Virtual Atoms
5.1.1.2
59
Broken Molecules and PBC
PLUMED is designed so that for the majority of the CVs implemented the periodic boundary conditions are treated
in the same manner as they would be treated in the host code. In some codes this can be problematic when
the colvars you are using involve some property of a molecule. These codes allow the atoms in the molecules to
become separated by periodic boundaries, a fact which PLUMED could only deal with were the topology passed
from the MD code to PLUMED. Making this work would involve a lot laborious programming and goes against our
original aim of having a general patch that can be implemented in a wide variety of MD codes. Consequentially,
we have implemented a more pragmatic solution to this problem - the user specifies in input any molecules (or
parts of molecules) that must be kept in tact throughout the simulation run. In PLUMED 1 this was done using
the ALIGN_ATOMS keyword. In PLUMED 2 the same effect can be achieved using the WHOLEMOLECULES
command.
The following input computes the end-to-end distance for a polymer of 100 atoms and keeps it at a value around 5.
BEGIN_PLUMED_FILE
WHOLEMOLECULES ENTITY0=1-100
e2e: DISTANCE ATOMS=1,100 NOPBC
RESTRAINT ARG=e2e KAPPA=1 AT=5
Notice that NOPBC is used to be sure in DISTANCE that if the end-to-end distance is larger than half the simulation
box the distance is compute properly. Also notice that, since many MD codes break molecules across cell boundary,
it might be necessary to use the WHOLEMOLECULES keyword (also notice that it should be before distance).
Notice that most expressions are invariant with respect to a change in the order of the atoms, but some of them
depend on that order. E.g., with WHOLEMOLECULES it could be useful to specify atom lists in a reversed order.
BEGIN_PLUMED_FILE
# to see the effect, one could dump the atoms as they were before molecule reconstruction:
# DUMPATOMS FILE=dump-broken.xyz ATOMS=1-20
WHOLEMOLECULES STRIDE=1 ENTITY0=1-20
DUMPATOMS FILE=dump.xyz ATOMS=1-20
Notice that there are other ways to manipulate the coordinates stored within PLUMED:
• Using the FIT_TO_TEMPLATE they can be aligned to a template structure.
• Using WRAPAROUND you can bring a set of atom as close as possible to another set of atoms.
• Using RESET_CELL you can rotate the periodic cell.
5.1.2
Virtual Atoms
Sometimes, when calculating a colvar, you may not want to use the positions of a number of atoms directly. Instead
you may wish to use the position of a virtual atom whose position is generated based on the positions of a collection
of other atoms. For example you might want to use the center of mass of a group of atoms. Plumed has a number
of routines for calculating the positions of these virtual atoms from lists of atoms:
CENTER_OF_MULTICOLVAR
CENTER
Calculate a a weighted average position based on the value of some multicolvar.
Calculate the center for a group of atoms, with arbitrary weights.
COM
Calculate the center of mass for a group of atoms.
FIXEDATOM
Add a virtual atom in a fixed position.
GHOST
Calculate the absolute position of a ghost atom with fixed coordinates in the
local reference frame formed by three atoms.
Generated by Doxygen
60
Collective Variables
To specify to a colvar that you want to use the position of a virtual atom to calculate a colvar rather than one of the
atoms in your system you simply use the label for your virtual atom in place of the usual numerical index. Virtual
atoms and normal atoms can be mixed together in the input to colvars as shown below:
BEGIN_PLUMED_FILE
COM ATOMS=1,10 LABEL=com1
DISTANCE ATOMS=11,com1
If you don't want to calculate CVs from the virtual atom. That is to say you just want to monitor the position of a
virtual atom (or any set of atoms) over the course of your trajectory you can do this using DUMPATOMS.
5.1.3
GROUP
This is part of the generic module
Define 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.
Atoms can be listed as comma separated numbers (i.e. 1,2,3,10,45,7,9) , simple positive ranges (i.←e. 20-40), ranges with a stride either positive or negative (i.e. 20-40:2 or 80-50:-2) or as comma separated
combinations of all the former methods (1,2,4,5,10-20,21-40:2,80-50:-2).
Moreover, lists can be imported from ndx files (GROMACS format). Use NDX_FILE to set the name of the index
file and NDX_GROUP to set the name of the group to be imported (default is first one).
It is also possible to remove atoms from a list and or sort them using keywords REMOVE, SORT, and UNIQUE. The
flow is the following:
• If ATOMS is present, then take the ordered list of atoms from the ATOMS keyword as a starting list.
• If NDX_FILE is present, then append to it the list obtained from the gromacs group.
• If REMOVE is present, then remove the first occurrence of each of these atoms from the list. If one tries to
remove an atom that was not listed plumed adds a notice in the output. An atom that is present twice in the
original list might be removed twice.
• If SORT is present, then the resulting list is sorted by increasing serial number.
• If UNIQUE is present, then the resulting list is sorted by increasing serial number and duplicate elements are
removed.
Notice that this command just creates a shortcut, and does not imply any real calculation. So, having a huge group
defined does not slow down your calculation in any way. It is just convenient to better organize input files. Might be
used in combination with the INCLUDE command so as to store long group definitions in a separate file.
The atoms involved can be specified using
ATOMS
the numerical indexes for the set of atoms in the group. For more information on how to specify lists
of atoms see Groups and Virtual Atoms
REMOVE
remove these atoms from the list. For more information on how to specify lists of atoms see
Groups and Virtual Atoms
Generated by Doxygen
5.1 Groups and Virtual Atoms
61
Options
SORT
( default=off ) sort the resulting list
UNIQUE
( default=off ) sort atoms and remove duplicated ones
NDX_FILE
the name of index file (gromacs syntax)
NDX_GROUP
the name of the group to be imported (gromacs syntax) - first group found is used by default
Examples
This command create a group of atoms containing atoms 1, 4, 7, 11 and 14 (labeled 'o'), and another containing
atoms 2, 3, 5, 6, 8, 9, 12, and 13 (labeled 'h'):
BEGIN_PLUMED_FILE
o: GROUP ATOMS=1,4,7,11,14
h: GROUP ATOMS=2,3,5,6,8,9,12,13
# compute the coordination among the two groups
c: COORDINATION GROUPA=o GROUPB=h R_0=0.3
# same could have been obtained without GROUP, just writing:
# c: COORDINATION GROUPA=1,4,7,11,14 GROUPB=2,3,5,6,8,9,12,13
# print the coordination on file ’colvar’
PRINT ARG=c FILE=colvar
Groups can be conveniently stored in a separate file. E.g. one could create a file named groups.dat which
reads
BEGIN_PLUMED_FILE
o: GROUP ATOMS=1,4,7,11,14
h: GROUP ATOMS=2,3,5,6,8,9,12,13
and then include it in the main 'plumed.dat' file
BEGIN_PLUMED_FILE
INCLUDE FILE=groups.dat
# compute the coordination among the two groups
c: COORDINATION GROUPA=o GROUPB=h R_0=0.3
# print the coordination on file ’colvar’
PRINT ARG=c FILE=colvar
The groups.dat file could be very long and include lists of thousand atoms without cluttering the main plumed.←dat file.
A GROMACS index file can also be imported
BEGIN_PLUMED_FILE
# import group named ’protein’ from file index.ndx
pro: GROUP NDX_FILE=index.ndx NDX_GROUP=protein
# dump all the atoms of the protein on a trajectory file
DUMPATOMS ATOMS=pro FILE=traj.gro
A list can be edited with REMOVE. For instance, if you are using a water model with three atoms per molecule, you
can easily construct the list of hydrogen atoms in this manner
BEGIN_PLUMED_FILE
# take one atom every three, that is oxygens
ox: GROUP ATOMS=1-90:3
# take the remaining atoms, that is hydrogens
hy: GROUP ATOMS=1-90 REMOVE=ox
DUMPATOMS ATOMS=ox FILE=ox.gro
DUMPATOMS ATOMS=hy FILE=hy.gro
5.1.4
MOLINFO
Generated by Doxygen
62
Collective Variables
This is part of the setup module
This command is used to provide information on the molecules that are present in your system.
The information on the molecules in your system can either be provided in the form of a pdb file or as a set of lists
of atoms that describe the various chains in your system. If a pdb file is used plumed the MOLINFO command will
endeavor to recognize the various chains and residues that make up the molecules in your system using the chain←IDs and resnumbers from the pdb file. You can then use this information in later commands to specify atom lists in
terms residues. For example using this command you can find the backbone atoms in your structure automatically.
Warning
Please be aware that the PDB parser in plumed is far from perfect. You should thus check the log file and
examine what plumed is actually doing whenever you use the MOLINFO action. Also make sure that the
atoms are listed in the pdb with the correct order. If you are using gromacs, the safest way is to use reference
pdb file generated with gmx editconf -f topol.tpr -o reference.pdb.
More information of the PDB parser implemented in PLUMED can be found at this page.
Providing MOLTYPE=protein, MOLTYPE=rna, or MOLTYPE=dna will instruct plumed to look for known
residues from these three types of molecule. In other words, this is available for historical reasons and to allow
future extensions where alternative lists will be provided. As of now, you can just ignore this keyword.
Using MOLINFO extends the possibility of atoms selection using the @ special symbol. The following shortcuts are
available that do not refer to one specific residue:
@nucleic : all atoms that are part of a DNA or RNA molecule
@protein : all atoms that are part of a protein
@water : all water molecules
@ions : all the ions
@hydrogens : all hydrogen atoms (those for which the first non-number in the name is a H)
@nonhydrogens : all non hydrogen atoms (those for which the first non-number in the name is not a H)
Warning
Be careful since these choices are based on common names used in PDB files. Always check if the selected
atoms are correct.
In addition, atoms from a specific residue can be selected with a symbol in this form:
@"definition"-chain_residuenum
@"definition"-chainresiduenum
@"definition"-residuenum
So for example
@psi-1 will select the atoms defining the psi torsion of residue 1
@psi-C1 or @psi-C_1 will define the same torsion for residue 1 of chain C.
@psi-3_1 will define the same torsion for residue 1 of chain 3.
Generated by Doxygen
5.1 Groups and Virtual Atoms
63
Using the underscore to separate chain and residue is available as of PLUMED 2.5 and allows selecting chains with
a numeric id.
In the following are listed the current available definitions:
For protein residues, the following groups are available:
@phi-#
@psi-#
@omega-#
@chi1-#
@chi2-#
@chi3-#
@chi4-#
@chi5-#
that select the appropriate atoms that define each dihedral angle for residue #.
For DNA or RNA residues, the following groups are available:
# quadruplets for backbone dihedral angles
@alpha-#
@beta-#
@gamma-#
@delta-#
@epsilon-#
@zeta-#
# quadruplets for sugar dihedral angles
@v0-#
@v1-#
@v2-#
@v3-#
@v4-#
# quadruplet corresponding to the chi torsional angle
@chi-#
# backbone, sugar, and base heavy atoms
@back-#
@sugar-#
@base-#
# ordered triplets of atoms on the 6-membered ring of nucleobases
# namely:
# C2/C4/C6 for pyrimidines
# C2/C6/C4 for purines
@lcs-#
Notice that zeta and epsilon groups should not be used on 3' end residue and alpha and beta should not
be used on 5' end residue.
Furthermore it is also possible to pick single atoms using the syntax atom-chain_residuenum,
@atom-chainresiduenum or @atom-residuenum. As of PLUMED 2.5, this also works when the residue
is not a protein/rna/dna residue. For instance, @OW-100 will select oxygen of water molecule with residue number
100.
Finally, notice that other shortcuts are available even when not using the MOLINFO command (see
Specifying Atoms).
Generated by Doxygen
64
Collective Variables
Warning
If a residue-chain is repeated twice in the reference pdb only the first entry will be selected.
Bug At the moment the HA1 atoms in a GLY residues are treated as if they are the CB atoms. This may or may not
be true - GLY is problematic for secondary structure residues as it is achiral.
Bug If you use WHOLEMOLECULES RESIDUES=1-10 for a 18 amino acid protein ( 18 amino acids + 2 terminal
groups = 20 residues ) the code will fail as it will not be able to interpret terminal residue 1.
The atoms involved can be specified using
CHAIN
(for masochists ( mostly Davide Branduardi ) ) The atoms involved in each of the chains of interest in
the structure.. For more information on how to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
STRUCTURE
a file in pdb format containing a reference structure. This is used to defines the atoms in the
various residues, chains, etc . For more details on the PDB file format visit http://www.←-
MOLTYPE
( default=protein ) what kind of molecule is contained in the pdb file - usually not needed since
protein/RNA/DNA are compatible
wwpdb.org/docs.html
Examples
In the following example the MOLINFO command is used to provide the information on which atoms are in the
backbone of a protein to the ALPHARMSD CV.
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=reference.pdb
ALPHARMSD RESIDUES=all TYPE=DRMSD LESS_THAN={RATIONAL R_0=0.08 NN=8 MM=12} LABEL=a
The following example prints the distance corresponding to the hydrogen bonds in a GC Watson-Crick pair.
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=reference.pdb
hb1: DISTANCE ATOMS=@N2-1,@O2-14
hb2: DISTANCE ATOMS=@N1-1,@N3-14
hb3: DISTANCE ATOMS=@O6-1,@N4-14
PRINT ARG=hb1,hb2,hb3
This example use MOLINFO to calculate torsion angles
BEGIN_PLUMED_FILE
MOLINFO MOLTYPE=protein STRUCTURE=myprotein.pdb
t1: TORSION ATOMS=@phi-3
t2: TORSION ATOMS=@psi-4
PRINT ARG=t1,t2 FILE=colvar STRIDE=10
5.1.5
WHOLEMOLECULES
Generated by Doxygen
5.1 Groups and Virtual Atoms
65
This is part of the generic module
This action is used to rebuild molecules that can become split by the periodic boundary conditions.
It is similar to the ALIGN_ATOMS keyword of plumed1, and is needed since some MD dynamics code (e.g. GR←OMACS) can break molecules during the calculation.
Running some CVs without this command can cause there to be discontinuities changes in the CV value and
artifacts in the calculations. This command can be applied more than once. To see what effect is has use a variable
without pbc or use the DUMPATOMS directive to output the atomic positions.
Attention
This directive modifies the stored position at the precise moment it is executed. This means that only collective
variables which are below it in the input script will see the corrected positions. As a general rule, put it at the
top of the input file. Also, unless you know exactly what you are doing, leave the default stride (1), so that this
action is performed at every MD step.
The way WHOLEMOLECULES modifies each of the listed entities is this:
• First atom of the list is left in place
• Each atom of the list is shifted by a lattice vectors so that it becomes as close as possible to the previous one,
iteratively.
In this way, if an entity consists of a list of atoms such that consecutive atoms in the list are always closer than half
a box side the entity will become whole. This can be usually achieved selecting consecutive atoms (1-100), but it is
also possible to skip some atoms, provided consecutive chosen atoms are close enough.
The atoms involved can be specified using
ENTITY
the atoms that make up a molecule that you wish to align. To specify multiple molecules use a list
of ENTITY keywords: ENTITY0, ENTITY1,... You can use multiple instances of this keyword i.e.
ENTITY1, ENTITY2, ENTITY3...
Or alternatively by using
RESIDUES
this command specifies that the backbone atoms in a set of residues all must be aligned. It must
be used in tandem with the MOLINFO action and the MOLTYPE keyword. If you wish to use all
the residues from all the chains in your system you can do so by specifying all. Alternatively, if you
wish to use a subset of the residues you can specify the particular residues you are interested in
as a list of numbers
Compulsory keywords
Generated by Doxygen
66
Collective Variables
STRIDE
( default=1 ) the frequency with which molecules are reassembled. Unless you are completely certain
about what you are doing leave this set equal to 1!
Options
ADDREFERENCE
( default=off ) Set this flag if you want to define a reference position for the first atom of
each entity
MOLTYPE
the type of molecule that is under study. This is used to define the backbone atoms
REF
Add reference position for first atom of each entity You can use multiple instances of this
keyword i.e. REF1, REF2, REF3...
Examples
This command instructs plumed to reconstruct the molecule containing atoms 1-20 at every step of the calculation
and dump them on a file.
BEGIN_PLUMED_FILE
# to see the effect, one could dump the atoms as they were before molecule reconstruction:
# DUMPATOMS FILE=dump-broken.xyz ATOMS=1-20
WHOLEMOLECULES ENTITY0=1-20
DUMPATOMS FILE=dump.xyz ATOMS=1-20
This command instructs plumed to reconstruct two molecules containing atoms 1-20 and 30-40
BEGIN_PLUMED_FILE
WHOLEMOLECULES ENTITY0=1-20 ENTITY1=30-40
DUMPATOMS FILE=dump.xyz ATOMS=1-20,30-40
This command instructs plumed to reconstruct the chain of backbone atoms in a protein
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=helix.pdb
WHOLEMOLECULES RESIDUES=all MOLTYPE=protein
5.1.6
FIT_TO_TEMPLATE
This is part of the generic module
This action is used to align a molecule to a template.
This can be used to move the coordinates stored in plumed so as to be aligned with a provided template in PDB
format. Pdb should contain also weights for alignment (see the format of PDB files used e.g. for RMSD). Make
sure your PDB file is correctly formatted as explained in this page. Weights for displacement are ignored, since no
displacement is computed here. Notice that all atoms (not only those in the template) are aligned. To see what
effect try the DUMPATOMS directive to output the atomic positions.
Generated by Doxygen
5.1 Groups and Virtual Atoms
67
Also notice that PLUMED propagate forces correctly so that you can add a bias on a CV computed after alignment.
For many CVs this has no effect, but in some case the alignment can change the result. Examples are:
• POSITION CV since it is affected by a rigid shift of the system.
• DISTANCE CV with COMPONENTS. Since the alignment could involve a rotation (with TYPE=OPTIMAL) the
actual components could be different from the original ones.
• CELL components for a similar reason.
• DISTANCE from a FIXEDATOM, provided the fixed atom is introduced after the FIT_TO_TEMPLATE action.
Attention
The implementation of TYPE=OPTIMAL is available but should be considered in testing phase. Please report
any strange behavior.
This directive modifies the stored position at the precise moment it is executed. This means that only collective
variables which are below it in the input script will see the corrected positions. As a general rule, put it at the
top of the input file. Also, unless you know exactly what you are doing, leave the default stride (1), so that this
action is performed at every MD step.
When running with periodic boundary conditions, the atoms should be in the proper periodic image. This is done
automatically since PLUMED 2.5, by considering the ordered list of atoms and rebuilding the molecules using a
procedure that is equivalent to that done in WHOLEMOLECULES . Notice that rebuilding is local to this action. This
is different from WHOLEMOLECULES which actually modifies the coordinates stored in PLUMED.
In case you want to recover the old behavior you should use the NOPBC flag. In that case you need to take care
that atoms are in the correct periodic image.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which molecules are reassembled. Unless you are completely
certain about what you are doing leave this set equal to 1!
REFERENCE
a file in pdb format containing the reference structure and the atoms involved in the CV.
TYPE
( default=SIMPLE ) the manner in which RMSD alignment is performed. Should be OPTIMAL
or SIMPLE.
Options
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
Examples
Align the atomic position to a template then print them. The following example is only translating the system so as
to align the center of mass of a molecule to the one in the reference structure ref.pdb:
BEGIN_PLUMED_FILE
Generated by Doxygen
68
Collective Variables
# dump coordinates before fitting, to see the difference:
DUMPATOMS FILE=dump-before.xyz ATOMS=1-20
# fit coordinates to ref.pdb template
# this is a "TYPE=SIMPLE" fit, so that only translations are used.
FIT_TO_TEMPLATE STRIDE=1 REFERENCE=ref.pdb TYPE=SIMPLE
# dump coordinates after fitting, to see the difference:
DUMPATOMS FILE=dump-after.xyz ATOMS=1-20
The following example instead performs a rototranslational fit.
BEGIN_PLUMED_FILE
# dump coordinates before fitting, to see the difference:
DUMPATOMS FILE=dump-before.xyz ATOMS=1-20
# fit coordinates to ref.pdb template
# this is a "TYPE=OPTIMAL" fit, so that rototranslations are used.
FIT_TO_TEMPLATE STRIDE=1 REFERENCE=ref.pdb TYPE=OPTIMAL
# dump coordinates after fitting, to see the difference:
DUMPATOMS FILE=dump-after.xyz ATOMS=1-20
In the following example you see two completely equivalent way to restrain an atom close to a position that is defined
in the reference frame of an aligned molecule. It could be for instance the center of mass of a ligand with respect to
a protein
BEGIN_PLUMED_FILE
# center of the ligand:
center: CENTER ATOMS=100-110
FIT_TO_TEMPLATE REFERENCE=protein.pdb TYPE=OPTIMAL
# place a fixed atom in the protein reference coordinates:
fix: FIXEDATOM AT=1.0,1.1,1.0
# take the distance between the fixed atom and the center of the ligand
d: DISTANCE ATOMS=center,fix
# apply a restraint
RESTRAINT ARG=d AT=0.0 KAPPA=100.0
Notice that you could have obtained an (almost) identical result adding a fictitious atom to ref.pdb with the serial
number corresponding to the atom labelled center (there is no automatic way to get it, but in this example it should
be the number of atoms of the system plus one), and properly setting the weights for alignment and displacement
in RMSD. There are two differences to be expected: (ab) FIT_TO_TEMPLATE might be slower since it has to
rototranslate all the available atoms and (b) variables employing periodic boundary conditions (such as DISTANCE
without NOPBC, as in the example above) are allowed after FIT_TO_TEMPLATE, whereas RMSD expects the
issues related to the periodic boundary conditions to be already solved. The latter means that before the RMSD
statement one should use WRAPAROUND or WHOLEMOLECULES to properly place the ligand.
5.1.7
WRAPAROUND
This is part of the generic module
Rebuild periodic boundary conditions around chosen atoms.
Modify position of atoms indicated by ATOMS by shifting them by lattice vectors so that they are as close as possible
to the atoms indicated by AROUND. More precisely, for every atom i in the ATOMS list the following procedure is
performed:
Generated by Doxygen
5.1 Groups and Virtual Atoms
69
• The atom j among those in the AROUND list is searched that is closest to atom i.
• The atom i is replaced with its periodic image that is closest to atom j.
This action works similarly to WHOLEMOLECULES in that it replaces atoms coordinate. Notice that only atoms
specified with ATOMS are replaced, and that, at variance with WHOLEMOLECULES, the order in which atoms are
specified is irrelevant.
This is often convenient at a post processing stage (using the driver), but sometime it is required during the simulation if collective variables need atoms to be in a specific periodic image.
Attention
This directive modifies the stored position at the precise moment it is executed. This means that only collective
variables which are below it in the input script will see the corrected positions. As a general rule, put it at the
top of the input file. Also, unless you know exactly what you are doing, leave the default stride (1), so that this
action is performed at every MD step.
Consider that the computational cost grows with the product of the size of the two lists (ATOMS and AROUND),
so that this action can become very expensive. If you are using it to analyze a trajectory this is usually not a big
problem. If you use it to analyze a simulation on the fly, e.g. with DUMPATOMS to store a properly wrapped
trajectory, consider the possibility of using the STRIDE keyword here (with great care).
The atoms involved can be specified using
AROUND
reference atoms. For more information on how to specify lists of atoms see Groups and Virtual Atoms
ATOMS
wrapped atoms. For more information on how to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
STRIDE
( default=1 ) the frequency with which molecules are reassembled. Unless you are completely
certain about what you are doing leave this set equal to 1!
GROUPBY
( default=1 ) group atoms so as not to break molecules
Examples
This command instructs plumed to move all the ions to their periodic image that is as close as possible to the rna
group.
BEGIN_PLUMED_FILE
rna: GROUP ATOMS=1-100
ions: GROUP ATOMS=101-110
# first make the rna molecule whole
WHOLEMOLECULES ENTITY0=rna
WRAPAROUND ATOMS=ions AROUND=rna
DUMPATOMS FILE=dump.xyz ATOMS=rna,ions
In case you want to do it during a simulation and you only care about wrapping the ions in the dump.xyz file, you
can use the following:
Generated by Doxygen
70
Collective Variables
BEGIN_PLUMED_FILE
# add some restraint that do not require molecules to be whole:
a: TORSION ATOMS=1,2,10,11
RESTRAINT ARG=a AT=0.0 KAPPA=5
# then do the things that are required for dumping the trajectory
# notice that they are all done every 100 steps, so as not to
# unnecessarily overload the calculation
rna: GROUP ATOMS=1-100
ions: GROUP ATOMS=101-110
# first make the rna molecule whole
WHOLEMOLECULES ENTITY0=rna STRIDE=100
WRAPAROUND ATOMS=ions AROUND=rna STRIDE=100
DUMPATOMS FILE=dump.xyz ATOMS=rna,ions STRIDE=100
Notice that if the biased variable requires a molecule to be whole, you might have to put just the
WHOLEMOLECULES command before computing that variable and leave the default STRIDE=1.
This command instructs plumed to center all atoms around the center of mass of a solute molecule.
BEGIN_PLUMED_FILE
solute: GROUP ATOMS=1-100
all: GROUP ATOMS=1-1000
# center of the solute:
# notice that since plumed 2.2 this also works if the
# solute molecule is broken
com: COM ATOMS=solute
# notice that we wrap around a single atom. this should be fast
WRAPAROUND ATOMS=all AROUND=com
DUMPATOMS FILE=dump.xyz ATOMS=all
Notice that whereas WHOLEMOLECULES is designed to make molecules whole, WRAPAROUND can easily break
molecules. In the last example, if solvent (atoms 101-1000) is made e.g. of water, then water molecules could be
broken by WRAPAROUND (hydrogen could end up in an image and oxygen in another one). One solution is to
use WHOLEMOLECULES on all the water molecules after WRAPAROUND. This is tedious. A better solution is to
use the GROUPBY option which is going to consider the atoms listed in ATOMS as a list of groups each of size
GROUPBY. The first atom of the group will be brought close to the AROUND atoms. The following atoms of the
group will be just brought close to the first atom of the group. Assuming that oxygen is the first atom of each water
molecules, in the following examples all the water oxygen atoms will be brought close to the solute, and all the
hydrogen atoms will be kept close to their related oxygen.
BEGIN_PLUMED_FILE
solute: GROUP ATOMS=1-100
water: GROUP ATOMS=101-1000
com: COM ATOMS=solute
# notice that we wrap around a single atom. this should be fast
WRAPAROUND ATOMS=solute AROUND=com
# notice that we wrap around a single atom. this should be fast
WRAPAROUND ATOMS=water AROUND=com GROUPBY=3
DUMPATOMS FILE=dump.xyz ATOMS=solute,water
5.1.8
RESET_CELL
This is part of the generic module
This action is used to rotate the full cell
Generated by Doxygen
5.1 Groups and Virtual Atoms
71
This can be used to modify the periodic box. Notice that this is done at fixed scaled coordinates, so that also atomic
coordinates for the entire system are affected. To see what effect try the DUMPATOMS directive to output the
atomic positions.
Also notice that PLUMED propagate forces correctly so that you can add a bias on a CV computed after rotation.
See also FIT_TO_TEMPLATE
Currently, only TYPE=TRIANGULAR is implemented, which allows one to reset the cell to a lower triangular one.
Namely, a proper rotation is found that allows rotating the box so that the first lattice vector is in the form (ax,0,0),
the second lattice vector is in the form (bx,by,0), and the third lattice vector is arbitrary.
Attention
The implementation of this action is available but should be considered in testing phase. Please report any
strange behavior.
This directive modifies the stored position at the precise moment it is executed. This means that only collective
variables which are below it in the input script will see the corrected positions. Unless you know exactly what
you are doing, leave the default stride (1), so that this action is performed at every MD step.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which molecules are reassembled. Unless you are completely certain
about what you are doing leave this set equal to 1!
TYPE
( default=TRIANGULAR ) the manner in which the cell is reset
Examples
Reset cell to be triangular after a rototranslational fit
BEGIN_PLUMED_FILE
DUMPATOMS FILE=dump-original.xyz ATOMS=1-20
FIT_TO_TEMPLATE STRIDE=1 REFERENCE=ref.pdb TYPE=OPTIMAL
DUMPATOMS FILE=dump-fit.xyz ATOMS=1-20
RESET_CELL TYPE=TRIANGULAR
DUMPATOMS FILE=dump-reset.xyz ATOMS=1-20
5.1.9
CENTER_OF_MULTICOLVAR
This is part of the multicolvar module
Calculate a a weighted average position based on the value of some multicolvar.
This action calculates the position of a new virtual atom using the following formula:
P
1
i wi fi sin (2πxi,α )
P
xα =
arctan
2π
i wi fi cos (2πxi,α )
Where in this expression the wi values are a set of weights calculated within a multicolvar action and the fi are the
values of the multicolvar functions. The xi,α values are the positions (in scaled coordinates) associated with each
of the multicolvars calculated.
Generated by Doxygen
72
Collective Variables
Bug The virial contribution for this type of virtual atom is not currently evaluated so do not use in bias functions
unless the volume of the cell is fixed
The atoms involved can be specified using
ATOMS
the list of atoms which are involved the virtual atom's definition. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
DATA
find the average value for a multicolvar
Options
COMPONENT
if your input multicolvar is a vector then specify which component you would like to use in
calculating the weight
Examples
Lets suppose that you are examining the formation of liquid droplets from gas. You may want to determine the center
of mass of any of the droplets formed. In doing this calculation you recognize that the atoms in the liquid droplets
will have a higher coordination number than those in the surrounding gas. As you want to calculate the position of
the droplets you thus recognize that these atoms with high coordination numbers should have a high weight in the
weighted average you are using to calculate the position of the droplet. You can thus calculate the position of the
droplet using an input like the one shown below:
BEGIN_PLUMED_FILE
c1: COORDINATIONNUMBER SPECIES=1-512 SWITCH={EXP D_0=4.0 R_0=0.5}
cc: CENTER_OF_MULTICOLVAR DATA=c1
The first line here calculates the coordination numbers of all the atoms in the system. The virtual atom then uses the
values of the coordination numbers calculated by the action labelled c1 when it calculates the Berry Phase average
described above. (N.B. the wi in the above expression are all set equal to 1 in this case)
The above input is fine we can, however, refine this somewhat by making use of a multicolvar transform action as
shown below:
BEGIN_PLUMED_FILE
c1: COORDINATIONNUMBER SPECIES=1-512 SWITCH={EXP D_0=4.0 R_0=0.5}
cf: MTRANSFORM_MORE DATA=c1 SWITCH={RATIONAL D_0=2.0 R_0=0.1} LOWMEM
cc: CENTER_OF_MULTICOLVAR DATA=cf
This input once again calculates the coordination numbers of all the atoms in the system. The middle line then
transforms these coordination numbers to numbers between 0 and 1. Essentially any atom with a coordination
number larger than 2.0 is given a weight of one and below this value the transformed value decays to zero. It
is these transformed coordination numbers that are used to calculate the Berry phase average described in the
previous section.
5.1.10
CENTER
Generated by Doxygen
5.1 Groups and Virtual Atoms
73
This is part of the vatom module
Calculate the center for a group of atoms, with arbitrary weights.
The computed center is stored as a virtual atom that can be accessed in an atom list through the label for the
CENTER action that creates it. Notice that the generated virtual atom has charge equal to the sum of the charges
and mass equal to the sum of the masses. If used with the MASS flag, then it provides a result identical to COM.
When running with periodic boundary conditions, the atoms should be in the proper periodic image. This is done
automatically since PLUMED 2.2, by considering the ordered list of atoms and rebuilding the molecule using a
procedure that is equivalent to that done in WHOLEMOLECULES . Notice that rebuilding is local to this action. This
is different from WHOLEMOLECULES which actually modifies the coordinates stored in PLUMED.
In case you want to recover the old behavior you should use the NOPBC flag. In that case you need to take care
that atoms are in the correct periodic image.
Note
As an experimental feature, CENTER also supports a keyword PHASES. This keyword finds the center of
mass for sets of atoms that have been split by the period boundaries by computing scaled coordinates and
average trigonometric functions, similarly to CENTER_OF_MULTICOLVAR. Notice that by construction this
center position is not invariant with respect to rotations of the atoms at fixed cell lattice. In addition, for
symmetric Bravais lattices, it is not invariant with respect to special symmetries. E.g., if you have an hexagonal
cell, the center will not be invariant with respect to rotations of 120 degrees. On the other hand, it might make
the treatment of PBC easier in difficult cases.
The atoms involved can be specified using
ATOMS
the list of atoms which are involved the virtual atom's definition. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Options
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
MASS
( default=off ) If set center is mass weighted
PHASES
( default=off ) Compute center using trigonometric phases
WEIGHTS
Center is computed as a weighted average.
Examples
BEGIN_PLUMED_FILE
# a point which is on the line connecting atoms 1 and 10, so that its distance
# from 10 is twice its distance from 1:
c1: CENTER ATOMS=1,1,10
# this is another way of stating the same:
c1bis: CENTER ATOMS=1,10 WEIGHTS=2,1
Generated by Doxygen
74
Collective Variables
# center of mass among these atoms:
c2: CENTER ATOMS=2,3,4,5 MASS
d1: DISTANCE ATOMS=c1,c2
PRINT ARG=d1
5.1.11
COM
This is part of the vatom module
Calculate the center of mass for a group of atoms.
The computed center of mass is stored as a virtual atom that can be accessed in an atom list through the label for
the COM action that creates it.
For arbitrary weights (e.g. geometric center) see CENTER.
When running with periodic boundary conditions, the atoms should be in the proper periodic image. This is done
automatically since PLUMED 2.2, by considering the ordered list of atoms and rebuilding the molecule using a
procedure that is equivalent to that done in WHOLEMOLECULES . Notice that rebuilding is local to this action. This
is different from WHOLEMOLECULES which actually modifies the coordinates stored in PLUMED.
In case you want to recover the old behavior you should use the NOPBC flag. In that case you need to take care
that atoms are in the correct periodic image.
The atoms involved can be specified using
ATOMS
the list of atoms which are involved the virtual atom's definition. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Options
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
MASS
( default=off ) If set center is mass weighted
PHASES
( default=off ) Compute center using trigonometric phases
WEIGHTS
Center is computed as a weighted average.
Examples
The following input instructs plumed to print the distance between the center of mass for atoms 1,2,3,4,5,6,7 and
that for atoms 15,20:
BEGIN_PLUMED_FILE
c1: COM ATOMS=1-7
c2: COM ATOMS=15,20
d1: DISTANCE ATOMS=c1,c2
PRINT ARG=d1
Generated by Doxygen
5.1 Groups and Virtual Atoms
5.1.12
75
FIXEDATOM
This is part of the vatom module
Add a virtual atom in a fixed position.
This action creates a virtual atom at a fixed position. The coordinates can be specified in Cartesian components
(by default) or in scaled coordinates (SCALED_COMPONENTS). It is also possible to assign a predefined charge
or mass to the atom.
Attention
Similar to POSITION this variable is not invariant for translation of the system. Adding a force on it can create
serious troubles.
Notice that the distance between to atoms created using FIXEDATOM is invariant for translation. Additionally, if one
first align atoms to a reference using FIT_TO_TEMPLATE, then it is safe to add further fixed atoms without breaking
translational invariance.
The atoms involved can be specified using
ATOMS
the list of atoms which are involved the virtual atom's definition. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
AT
SET_MASS
coordinates of the virtual atom
( default=1 ) mass of the virtual atom
SET_CHARGE
( default=0 ) charge of the virtual atom
Options
SCALED_COMPONENTS
( default=off ) use scaled components
Examples
The following input instructs plumed to compute the angle between distance of atoms 15 and 20 and the z axis and
keeping it close to zero.
BEGIN_PLUMED_FILE
a: FIXEDATOM AT=0,0,0
b: FIXEDATOM AT=0,0,1
an: ANGLE ATOMS=a,b,15,20
RESTRAINT ARG=an AT=0.0 KAPPA=100.0
Generated by Doxygen
76
Collective Variables
The following input instructs plumed to align a protein on a template and then compute the distance of one of its
atom from the point (10,20,30).
BEGIN_PLUMED_FILE
FIT_TO_TEMPLATE STRIDE=1 REFERENCE=ref.pdb TYPE=SIMPLE
a: FIXEDATOM AT=10,20,30
d: DISTANCE ATOMS=a,20
PRINT ARG=d FILE=colvar
5.1.13
GHOST
This is part of the vatom module
Calculate the absolute position of a ghost atom with fixed coordinates in the local reference frame formed by three
atoms.
The computed ghost atom is stored as a virtual atom that can be accessed in an atom list through the the label for
the GHOST action that creates it.
The atoms involved can be specified using
ATOMS
the list of atoms which are involved the virtual atom's definition. For more information on how
to specify lists of atoms see Groups and Virtual Atoms
COORDINATES
coordinates of the ghost atom in the local reference frame. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Examples
The following input instructs plumed to print the distance between the ghost atom and the center of mass for atoms
15,20:
BEGIN_PLUMED_FILE
c1: GHOST ATOMS=1,5,10 COORDINATES=10.0,10.0,10.0
c2: COM ATOMS=15,20
d1: DISTANCE ATOMS=c1,c2
PRINT ARG=d1
5.2
CV Documentation
The following list contains descriptions of a number of the colvars that are currently implemented in PLUMED.
ADAPTIVE_PATH
Compute path collective variables that adapt to the lowest free energy path
connecting states A and B.
ALPHABETA
Measures a distance including pbc between the instantaneous values of a
set of torsional angles and set of reference values.
ALPHARMSD
Probe the alpha helical content of a protein structure.
ANGLE
Calculate an angle.
Generated by Doxygen
5.2 CV Documentation
77
ANTIBETARMSD
Probe the antiparallel beta sheet content of your protein structure.
CELL
Calculate the components of the simulation cell
CONSTANT
Return one or more constant quantities with or without derivatives.
CONTACTMAP
Calculate the distances between a number of pairs of atoms and transform
each distance by a switching function.
COORDINATION
DHENERGY
Calculate coordination numbers.
Calculate Debye-Huckel interaction energy among GROUPA and GROUPB.
DIHCOR
Measures the degree of similarity between dihedral angles.
DIMER
This CV computes the dimer interaction energy for a collection of dimers.
DIPOLE
Calculate the dipole moment for a group of atoms.
DISTANCE_FROM_CONTOUR
DISTANCE
Calculate the perpendicular distance from a Willard-Chandler dividing surface.
Calculate the distance between a pair of atoms.
EEFSOLV
Calculates EEF1 solvation free energy for a group of atoms.
ENERGY
Calculate the total energy of the simulation box.
ERMSD
Calculate eRMSD with respect to a reference structure.
EXTRACV
FAKE
XX
This is a fake colvar container used by cltools or various other actions that
supports input and period definitions
GPROPERTYMAP
Property maps but with a more flexible framework for the distance metric
being used.
GYRATION
Calculate the radius of gyration, or other properties related to it.
PARABETARMSD
Probe the parallel beta sheet content of your protein structure.
PATHMSD
This Colvar calculates path collective variables.
PATH
Path collective variables with a more flexible framework for the distance metric being used.
PCAVARS
Projection on principal component eigenvectors or other high dimensional
linear subspace
POSITION
Calculate the components of the position of an atom.
PROPERTYMAP
Calculate generic property maps.
PUCKERING
Calculate sugar pseudorotation coordinates.
TEMPLATE
This file provides a template for if you want to introduce a new CV.
TORSION
Calculate a torsional angle.
VOLUME
Calculate the volume of the simulation box.
In addition to the keywords above, by enabling optional modules you can access to the following keywords:
CS2BACKBONE
(from PLUMED-ISDB module) Calculates the backbone chemical shifts for a protein.
EMMI
(from PLUMED-ISDB module) Calculate the fit of a structure or ensemble of structures with
a cryo-EM density map.
FRET
(from PLUMED-ISDB module) Calculates the FRET efficiency between a pair of atoms.The
efficiency is calculated using the Forster relation:
JCOUPLING
(from PLUMED-ISDB module) Calculates 3 J coupling constants for a dihedral angle.
NOE
(from PLUMED-ISDB module) Calculates NOE intensities as sums of 1/r∧ 6, also averaging
over multiple equivalent atoms or ambiguous NOE.
PCS
(from PLUMED-ISDB module) Calculates the Pseudo-contact shift of a nucleus determined
by the presence of a metal ion susceptible to anisotropic magnetization.
PIV
(from PIV collective variable module) Calculates the PIV-distance.
PRE
(from PLUMED-ISDB module) Calculates the Paramagnetic Resonance Enhancement intensity ratio between a spin label atom and a list of atoms .
Generated by Doxygen
78
Collective Variables
RDC
(from PLUMED-ISDB module) Calculates the (Residual) Dipolar Coupling between two
atoms.
(from PLUMED-ISDB module) Calculates SAXS scattered intensity using either the Debye
equation or the harmonic sphere approximation.
SAXS
5.2.1
ADAPTIVE_PATH
This is part of the mapping module
Compute path collective variables that adapt to the lowest free energy path connecting states A and B.
The Path Collective Variables developed by Branduardi and co-workers [5] allow one to compute the progress
along a high-dimensional path and the distance from the high-dimensional path. The progress along the path (s) is
computed using:
s = i2 + sign(i2 − i1 )
p
(v1 · v2 )2 − |v3 |2 (|v1 |2 − |v2 |2 ) v1 · v3 − |v3 |2
−
2|v3 |2
2|v3 |2
In this expression v1 and v3 are the vectors connecting the current position to the closest and second closest node
of the path, respectfully and i1 and i2 are the projections of the closest and second closest frames of the path. v2 ,
meanwhile, is the vector connecting the closest frame to the second closest frame. The distance from the path, z is
calculated using:
v"
u
u
z = t |v1 |2 − |v2 |
p
(v1 · v2 )2 − |v3 |2 (|v1 |2 − |v2 |2 ) v1 · v3 − |v3 |2
−
2|v3 |2
2|v3 |2
!#2
Notice that these are the definitions of s and z that are used by PATH when the GPATH option is employed. The
reason for this is that the adaptive path method implemented in this action was inspired by the work of Diaz and
Ensing in which these formula were used [4]. To learn more about how the path is adapted we strongly recommend
reading this paper.
Compulsory keywords
REFERENCE
a pdb file containing the set of reference configurations
TYPE
( default=OPTIMAL-FAST ) the manner in which distances are calculated. More information on
the different metrics that are available in PLUMED can be found in the section of the manual
on Distances from reference configurations
FIXED
the positions in the list of input frames of the two path nodes whose positions remain fixed
during the path optimization
HALFLIFE
( default=-1 ) the number of MD steps after which a previously measured path distance weighs
only 50% in the average. This option may increase convergence by allowing to "forget" the
memory of a bad initial guess path. The default is to set this to infinity
UPDATE
the frequency with which the path should be updated
TOLERANCE
( default=1E-6 ) the tolerance to use for the path updating algorithm that makes all frames
equidistant
FMT
( default=f ) the format to use for output files
Generated by Doxygen
5.2 CV Documentation
79
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
DISABLE_CHECKS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) disable checks on reference input structures.
WFILE
file on which to write out the path
WSTRIDE
frequency with which to write out the path
Examples
The input below provides an example that shows how the adaptive path works. The path is updated every 50 steps
of MD based on the data accumulated during the preceding 50 time steps.
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=1,2 COMPONENTS
pp: ADAPTIVE_PATH TYPE=EUCLIDEAN FIXED=5,15 UPDATE=50 WFILE=out-path.pdb WSTRIDE=50 REFERENCE=mypath.pdb
PRINT ARG=d1.x,d1.y,pp.* FILE=colvar
In the case above the distance between frames is calculated based on the x and y components of the vector
connecting atoms 1 and 2. As such an extract from the input reference path (mypath.pdb) would look as follows:
REMARK ARG=d1.x,d1.y d1.x=1.12 d1.y=-.60
END
REMARK ARG=d1.x,d1.y d1.x=.99 d1.y=-.45
END
Notice that one can also use RMSD frames in place of arguments like those above.
5.2.2
ALPHABETA
This is part of the multicolvar module
Measures a distance including pbc between the instantaneous values of a set of torsional angles and set of reference values.
This colvar calculates the following quantity.
s=
i
1 Xh
1 + cos(φi − φRef
)
i
2 i
Ref values are the
where the φi values are the instantaneous values for the TORSION angles of interest. The φi
user-specified reference values for the torsional angles.
Generated by Doxygen
80
Collective Variables
The atoms involved can be specified using
ATOMS
the atoms involved in each of the alpha-beta variables you wish to calculate. Keywords like ATOMS1,
ATOMS2, ATOMS3,... should be listed and one alpha-beta values will be calculated for each ATOM
keyword you specify (all ATOM keywords should specify the indices of four atoms). The eventual
number of quantities calculated by this action will depend on what functions of the distribution you
choose to calculate. You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATO←MS3...
Compulsory keywords
REFERENCE
the reference values for each of the torsional angles. If you use a single REFERENCE value
the same reference value is used for all torsional angles You can use multiple instances of this
keyword i.e. REFERENCE1, REFERENCE2, REFERENCE3...
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
COEFFICIENT
the coefficient for each of the torsional angles. If you use a single COEFFI←CIENT value the same reference value is used for all torsional angles You can
use multiple instances of this keyword i.e. COEFFICIENT1, COEFFICIENT2,
COEFFICIENT3...
Examples
The following provides an example of the input for an alpha beta similarity.
BEGIN_PLUMED_FILE
ALPHABETA ...
ATOMS1=168,170,172,188 REFERENCE1=3.14
ATOMS2=170,172,188,190 REFERENCE2=3.14
ATOMS3=188,190,192,230 REFERENCE3=3.14
LABEL=ab
... ALPHABETA
PRINT ARG=ab FILE=colvar STRIDE=10
Because all the reference values are the same we can calculate the same quantity using
Generated by Doxygen
5.2 CV Documentation
81
BEGIN_PLUMED_FILE
ALPHABETA ...
ATOMS1=168,170,172,188 REFERENCE=3.14
ATOMS2=170,172,188,190
ATOMS3=188,190,192,230
LABEL=ab
... ALPHABETA
PRINT ARG=ab FILE=colvar STRIDE=10
Writing out the atoms involved in all the torsion angles in this way can be rather tedious. Thankfully if you are working
with protein you can avoid this by using the MOLINFO command. PLUMED uses the pdb file that you provide to
this command to learn about the topology of the protein molecule. This means that you can specify torsion angles
using the following syntax:
BEGIN_PLUMED_FILE
MOLINFO MOLTYPE=protein STRUCTURE=myprotein.pdb
ALPHABETA ...
ATOMS1=@phi-3 REFERENCE=3.14
ATOMS2=@psi-3
ATOMS3=@phi-4
LABEL=ab
... ALPHABETA
PRINT ARG=ab FILE=colvar STRIDE=10
Here, @phi-3 tells plumed that you would like to calculate the φ angle in the third residue of the protein. Similarly
@psi-4 tells plumed that you want to calculate the ψ angle of the fourth residue of the protein.
5.2.3
ALPHARMSD
This is part of the secondarystructure module
Probe the alpha helical content of a protein structure.
Any chain of six contiguous residues in a protein chain can form an alpha helix. This colvar thus generates the set of
all possible six residue sections and calculates the RMSD distance between the configuration in which the residues
find themselves and an idealized alpha helical structure. These distances can be calculated by either aligning the
instantaneous structure with the reference structure and measuring each atomic displacement or by calculating
differences between the set of inter-atomic distances in the reference and instantaneous structures.
This colvar is based on the following reference [6]. The authors of this paper use the set of distances from the alpha
helix configurations to measure the number of segments that have an alpha helical configuration. This is done by
calculating the following sum of functions of the rmsd distances:
s=
X 1−
ri −d0
r0
1−
ri −d0
r0
i
n
m
where the sum runs over all possible segments of alpha helix. By default the NN, MM and D_0 parameters are set
equal to those used in [6]. The R_0 parameter must be set by the user - the value used in [6] was 0.08 nm.
If you change the function in the above sum you can calculate quantities such as the average distance from a purely
the alpha helical configuration or the distance between the set of residues that is closest to an alpha helix and the
reference configuration. To do these sorts of calculations you can use the AVERAGE and MIN keywords. In addition
Generated by Doxygen
82
Collective Variables
you can use the LESS_THAN keyword if you would like to change the form of the switching function. If you use any
of these options you no longer need to specify NN, R_0, MM and D_0.
Please be aware that for codes like gromacs you must ensure that plumed reconstructs the chains involved in your
CV when you calculate this CV using anything other than TYPE=DRMSD. For more details as to how to do this see
WHOLEMOLECULES.
Description of components
By default this Action calculates the number of structural units that are within a certain distance of a idealized
secondary structure element. This quantity can then be referenced elsewhere in the input by using the label of
the action. However, this Action can also be used to calculate the following quantities by using the keywords as
described below. The quantities then calculated can be referenced using the label of the action followed by a dot
and then the name from the table below. Please note that you can use the LESS_THAN keyword more than once.
The resulting components will be labelled label.lessthan-1, label.lessthan-2 and so on unless you exploit the fact
that these labels can be given custom labels by using the LABEL keyword in the description of you LESS_THAN
function that you are computing
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
The atoms involved can be specified using
RESIDUES
this command is used to specify the set of residues that could conceivably form part of the secondary structure. It is possible to use residues numbers as the various chains and residues
should have been identified else using an instance of the MOLINFO action. If you wish to use all
the residues from all the chains in your system you can do so by specifying all. Alternatively, if you
wish to use a subset of the residues you can specify the particular residues you are interested in
as a list of numbers. Please be aware that to form secondary structure elements your chain must
contain at least N residues, where N is dependent on the particular secondary structure you are
interested in. As such if you define portions of the chain with fewer than N residues the code will
crash.
Compulsory keywords
TYPE
R_0
( default=DRMSD ) the manner in which RMSD alignment is performed. Should be OPTIMAL, SIMPLE
or DRMSD. For more details on the OPTIMAL and SIMPLE methods see RMSD. For more details on
the DRMSD method see DRMSD.
( default=0.08 ) The r_0 parameter of the switching function.
D_0
( default=0.0 ) The d_0 parameter of the switching function
Generated by Doxygen
5.2 CV Documentation
83
NN
( default=8 ) The n parameter of the switching function
MM
( default=12 ) The m parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions
VERBOSE
( default=off ) write a more detailed output
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
MIN
ALT_MIN
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Examples
The following input calculates the number of six residue segments of protein that are in an alpha helical configuration.
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=helix.pdb
alpha: ALPHARMSD RESIDUES=all
Here the same is done use RMSD instead of DRMSD
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=helix.pdb
WHOLEMOLECULES ENTITY0=1-100
alpha: ALPHARMSD RESIDUES=all TYPE=OPTIMAL R_0=0.1
Generated by Doxygen
84
5.2.4
Collective Variables
ANGLE
This is part of the colvar module
Calculate an angle.
This command can be used to compute the angle between three atoms. Alternatively if four atoms appear in the
atom specification it calculates the angle between two vectors identified by two pairs of atoms.
If three atoms are given, the angle is defined as:
θ = arccos
r21 · r23
|r21 ||r23 |
Here rij is the distance vector among the ith and the j th listed atom.
If four atoms are given, the angle is defined as:
θ = arccos
r21 · r34
|r21 ||r34 |
Notice that angles defined in this way are non-periodic variables and their value is limited by definition between 0
and π .
The vectors rij are by default evaluated taking periodic boundary conditions into account. This behavior can be
changed with the NOPBC flag.
The atoms involved can be specified using
ATOMS
the list of atoms involved in this collective variable (either 3 or 4 atoms). For more information on how
to specify lists of atoms see Groups and Virtual Atoms
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
Examples
This command tells plumed to calculate the angle between the vector connecting atom 1 to atom 2 and the vector
connecting atom 2 to atom 3 and to print it on file COLVAR1. At the same time, the angle between vector connecting
atom 1 to atom 2 and the vector connecting atom 3 to atom 4 is printed on file COLVAR2.
BEGIN_PLUMED_FILE
a: ANGLE ATOMS=1,2,3
# equivalently one could state:
Generated by Doxygen
5.2 CV Documentation
85
# a: ANGLE ATOMS=1,2,2,3
b: ANGLE ATOMS=1,2,3,4
PRINT ARG=a FILE=COLVAR1
PRINT ARG=b FILE=COLVAR2
5.2.5
ANTIBETARMSD
This is part of the secondarystructure module
Probe the antiparallel beta sheet content of your protein structure.
Two protein segments containing three contiguous residues can form an antiparallel beta sheet. Although if the
two segments are part of the same protein chain they must be separated by a minimum of 2 residues to make
room for the turn. This colvar thus generates the set of all possible six residue sections that could conceivably form
an antiparallel beta sheet and calculates the RMSD distance between the configuration in which the residues find
themselves and an idealized antiparallel beta sheet structure. These distances can be calculated by either aligning
the instantaneous structure with the reference structure and measuring each atomic displacement or by calculating
differences between the set of inter-atomic distances in the reference and instantaneous structures.
This colvar is based on the following reference [6]. The authors of this paper use the set of distances from the anti
parallel beta sheet configurations to measure the number of segments that have an configuration that resembles an
anti parallel beta sheet. This is done by calculating the following sum of functions of the rmsd distances:
s=
X 1−
ri −d0
r0
1−
ri −d0
r0
i
n
m
where the sum runs over all possible segments of antiparallel beta sheet. By default the NN, MM and D_0 parameters are set equal to those used in [6]. The R_0 parameter must be set by the user - the value used in [6] was 0.08
nm.
If you change the function in the above sum you can calculate quantities such as the average distance from a purely
configuration composed of pure anti-parallel beta sheets or the distance between the set of residues that is closest
to an anti-parallel beta sheet and the reference configuration. To do these sorts of calculations you can use the
AVERAGE and MIN keywords. In addition you can use the LESS_THAN keyword if you would like to change the
form of the switching function. If you use any of these options you no longer need to specify NN, R_0, MM and D_0.
Please be aware that for codes like gromacs you must ensure that plumed reconstructs the chains involved in your
CV when you calculate this CV using anything other than TYPE=DRMSD. For more details as to how to do this see
WHOLEMOLECULES.
Description of components
By default this Action calculates the number of structural units that are within a certain distance of a idealized
secondary structure element. This quantity can then be referenced elsewhere in the input by using the label of
the action. However, this Action can also be used to calculate the following quantities by using the keywords as
described below. The quantities then calculated can be referenced using the label of the action followed by a dot
and then the name from the table below. Please note that you can use the LESS_THAN keyword more than once.
The resulting components will be labelled label.lessthan-1, label.lessthan-2 and so on unless you exploit the fact
that these labels can be given custom labels by using the LABEL keyword in the description of you LESS_THAN
function that you are computing
Generated by Doxygen
86
Collective Variables
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
The atoms involved can be specified using
RESIDUES
this command is used to specify the set of residues that could conceivably form part of the secondary structure. It is possible to use residues numbers as the various chains and residues
should have been identified else using an instance of the MOLINFO action. If you wish to use all
the residues from all the chains in your system you can do so by specifying all. Alternatively, if you
wish to use a subset of the residues you can specify the particular residues you are interested in
as a list of numbers. Please be aware that to form secondary structure elements your chain must
contain at least N residues, where N is dependent on the particular secondary structure you are
interested in. As such if you define portions of the chain with fewer than N residues the code will
crash.
Compulsory keywords
TYPE
R_0
( default=DRMSD ) the manner in which RMSD alignment is performed. Should be OPTIMAL, S←IMPLE or DRMSD. For more details on the OPTIMAL and SIMPLE methods see RMSD. For more
details on the DRMSD method see DRMSD.
( default=0.08 ) The r_0 parameter of the switching function.
D_0
( default=0.0 ) The d_0 parameter of the switching function
NN
( default=8 ) The n parameter of the switching function
MM
( default=12 ) The m parameter of the switching function
STYLE
( default=all ) Antiparallel beta sheets can either form in a single chain or from a pair of chains. If
STYLE=all all chain configuration with the appropriate geometry are counted. If STYLE=inter only
sheet-like configurations involving two chains are counted, while if STYLE=intra only sheet-like configurations involving a single chain are counted
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions
VERBOSE
( default=off ) write a more detailed output
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Generated by Doxygen
5.2 CV Documentation
LESS_THAN
MIN
87
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
ALT_MIN
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
STRANDS_CUTOFF
If in a segment of protein the two strands are further apart then the calculation
of the actual RMSD is skipped as the structure is very far from being beta-sheet
like. This keyword speeds up the calculation enormously when you are using
the LESS_THAN option. However, if you are using some other option, then this
cannot be used
Examples
The following input calculates the number of six residue segments of protein that are in an antiparallel beta sheet
configuration.
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=beta.pdb
ab: ANTIBETARMSD RESIDUES=all STRANDS_CUTOFF=1
Here the same is done use RMSD instead of DRMSD
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=helix.pdb
WHOLEMOLECULES ENTITY0=1-100
hh: ANTIBETARMSD RESIDUES=all TYPE=OPTIMAL R_0=0.1
5.2.6
STRANDS_CUTOFF=1
CELL
This is part of the colvar module
Calculate the components of the simulation cell
Generated by Doxygen
88
Collective Variables
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
ax
the ax component of the cell matrix
ay
the ay component of the cell matrix
az
the az component of the cell matrix
bx
the bx component of the cell matrix
by
the by component of the cell matrix
bz
the bz component of the cell matrix
cx
the cx component of the cell matrix
cy
the cy component of the cell matrix
cz
the cz component of the cell matrix
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
Examples
The following input tells plumed to print the squared modulo of each of the three lattice vectors
BEGIN_PLUMED_FILE
cell: CELL
aaa:
COMBINE ARG=cell.ax,cell.ay,cell.az POWERS=2,2,2 PERIODIC=NO
bbb:
COMBINE ARG=cell.bx,cell.by,cell.bz POWERS=2,2,2 PERIODIC=NO
ccc:
COMBINE ARG=cell.cx,cell.cy,cell.cz POWERS=2,2,2 PERIODIC=NO
PRINT ARG=aaa,bbb,ccc
5.2.7
CONSTANT
This is part of the colvar module
Return one or more constant quantities with or without derivatives.
Useful in combination with functions that takes in input constants or parameters.
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Generated by Doxygen
5.2 CV Documentation
89
Quantity
Description
v
the # value
Options
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
NODE←RIV
VALUES
VALUE
( default=off ) Set to TRUE if you want values without derivatives.
The values of the constants
The value of the constant
Examples
The following input instructs plumed to compute the distance between atoms 1 and 2. If this distance is between
1.0 and 2.0, it is printed. If it is lower than 1.0 (larger than 2.0), 1.0 (2.0) is printed
BEGIN_PLUMED_FILE
cn: CONSTANT VALUES=1.0,2.0
dis: DISTANCE ATOMS=1,2
sss: SORT ARG=cn.v_0,dis,cn.v_1
PRINT ARG=sss.2
In case you want to pass a single value you can use VALUE:
BEGIN_PLUMED_FILE
cn: CONSTANT VALUE=1.0
dis: DISTANCE ATOMS=1
sss: SORT ARG=cn,dis
PRINT ARG=sss.1
5.2.8
CONTACTMAP
This is part of the colvar module
Calculate the distances between a number of pairs of atoms and transform each distance by a switching function.
The transformed distance can be compared with a reference value in order to calculate the squared distance between two contact maps. Each distance can also be weighted for a given value. CONTACTMAP can be used
together with FUNCPATHMSD to define a path in the contactmap space.
The individual contact map distances related to each contact can be accessed as components named cm.←-
contact-1, cm.contact-2, etc, assuming that the label of the CONTACTMAP is cm.
Description of components
Generated by Doxygen
90
Collective Variables
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
contact
By not using SUM or CMDIST each contact will be stored in a component
The atoms involved can be specified using
ATOMS
the atoms involved in each of the contacts you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one contact will be calculated for each ATOM keyword you specify.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Compulsory keywords
SWITCH
The switching functions to use for each of the contacts in your map. You can either specify a global
switching function using SWITCH or one switching function for each contact. Details of the various
switching functions you can use are provided on switchingfunction. You can use multiple instances
of this keyword i.e. SWITCH1, SWITCH2, SWITCH3...
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) calculate the sum of all the contacts in the input
SUM
CMDIST
( default=off ) calculate the distance with respect to the provided reference
contact map
SERIAL
( default=off ) Perform the calculation in serial - for debug purpose
REFERENCE
A reference value for a given contact, by default is 0.0 You can either specify
a global reference value using REFERENCE or one reference value for each
contact. You can use multiple instances of this keyword i.e. REFERENCE1,
REFERENCE2, REFERENCE3...
WEIGHT
A weight value for a given contact, by default is 1.0 You can either specify a
global weight value using WEIGHT or one weight value for each contact. You
can use multiple instances of this keyword i.e. WEIGHT1, WEIGHT2, WEIG←HT3...
Examples
The following example calculates switching functions based on the distances between atoms 1 and 2, 3 and 4 and
4 and 5. The values of these three switching functions are then output to a file named colvar.
Generated by Doxygen
5.2 CV Documentation
91
BEGIN_PLUMED_FILE
CONTACTMAP ATOMS1=1,2 ATOMS2=3,4 ATOMS3=4,5 ATOMS4=5,6 SWITCH={RATIONAL R_0=1.5} LABEL=f1
PRINT ARG=f1.* FILE=colvar
The following example calculates the difference of the current contact map with respect to a reference provided. In
this case REFERENCE is the fraction of contact that is formed (i.e. the distance between two atoms transformed
with the SWITCH), while R_0 is the contact distance. WEIGHT gives the relative weight of each contact to the final
distance measure.
BEGIN_PLUMED_FILE
CONTACTMAP ...
ATOMS1=1,2 REFERENCE1=0.1 WEIGHT1=0.5
ATOMS2=3,4 REFERENCE2=0.5 WEIGHT2=1.0
ATOMS3=4,5 REFERENCE3=0.25 WEIGHT3=1.0
ATOMS4=5,6 REFERENCE4=0.0 WEIGHT4=0.5
SWITCH={RATIONAL R_0=1.5}
LABEL=cmap
CMDIST
... CONTACTMAP
PRINT ARG=cmap FILE=colvar
The next example calculates calculates fraction of native contacts (Q) for Trp-cage mini-protein. R_0 is the distance
at which the switch function is guaranteed to be 1.0 – it doesn't really matter for Q and should be something very
small, like 1 A. REF is the reference distance for the contact, e.g. the distance from a crystal structure. LAMBDA
is the tolerance for the distance – if set to 1.0, the contact would have to have exactly the reference value to be
formed; instead for lambda values of 1.5–1.8 are usually used to allow some slack. BETA is the softness of the
switch function, default is 50nm. WEIGHT is the 1/(number of contacts) giving equal weight to each contact.
When using native contact Q switch function, please cite [7]
BEGIN_PLUMED_FILE
# Full example available in regtest/basic/rt72/
CONTACTMAP ...
ATOMS1=1,67 SWITCH1={Q R_0=0.01 BETA=50.0 LAMBDA=1.5 REF=0.4059} WEIGHT1=0.003597
ATOMS2=1,68 SWITCH2={Q R_0=0.01 BETA=50.0 LAMBDA=1.5 REF=0.4039} WEIGHT2=0.003597
ATOMS3=1,69 SWITCH3={Q R_0=0.01 BETA=50.0 LAMBDA=1.5 REF=0.3215} WEIGHT3=0.003597
[snip]
ATOMS275=183,213 SWITCH275={Q R_0=0.01 BETA=50.0 LAMBDA=1.5 REF=0.355} WEIGHT275=0.003597
ATOMS276=183,234 SWITCH276={Q R_0=0.01 BETA=50.0 LAMBDA=1.5 REF=0.428} WEIGHT276=0.003597
ATOMS277=183,250 SWITCH277={Q R_0=0.01 BETA=50.0 LAMBDA=1.5 REF=0.3832} WEIGHT277=0.003597
ATOMS278=197,220 SWITCH278={Q R_0=0.01 BETA=50.0 LAMBDA=1.5 REF=0.3827} WEIGHT278=0.003597
LABEL=cmap
SUM
... CONTACTMAP
PRINT ARG=cmap FILE=colvar
(See also switchingfunction)
5.2.9
COORDINATION
This is part of the colvar module
Calculate coordination numbers.
Generated by Doxygen
92
Collective Variables
This keyword can be used to calculate the number of contacts between two groups of atoms and is defined as
XX
sij
i∈A i∈B
where sij is 1 if the contact between atoms i and j is formed, zero otherwise. In actuality, sij is replaced with a
switching function to make it differentiable. The default switching function is:
1−
rij −d0
r0
1−
rij −d0
r0
sij =
n
m
but it can be changed using the optional SWITCH option.
To make your calculation faster you can use a neighbor list, which makes it that only a relevant subset of the pairwise
distance are calculated at every step.
N (N −1)
pairs in GROUPA. This avoids computing twice permuted indexes (e.g.
If GROUPB is empty, it will sum the
2
pair (i,j) and (j,i)) thus running at twice the speed.
Notice that if there are common atoms between GROUPA and GROUPB the switching function should be equal to
one. These "self contacts" are discarded by plumed (since version 2.1), so that they actually count as "zero".
The atoms involved can be specified using
GROUPA
First list of atoms.
For more information on how to specify lists of atoms see
Groups and Virtual Atoms
GROUPB
Second list of atoms (if empty, N∗(N-1)/2 pairs in GROUPA are counted). For more information on
how to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Perform the calculation in serial - for debug purpose
SERIAL
PAIR
( default=off ) Pair only 1st element of the 1st group with 1st element in the
second, etc
NLIST
( default=off ) Use a neighbor list to speed up the calculation
Generated by Doxygen
5.2 CV Documentation
93
NL_CUTOFF
The cutoff for the neighbor list
NL_STRIDE
The frequency with which we are updating the atoms in the neighbor list
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
Examples
The following example instructs plumed to calculate the total coordination number of the atoms in group 1-10 with
the atoms in group 20-100. For atoms 1-10 coordination numbers are calculated that count the number of atoms
from the second group that are within 0.3 nm of the central atom. A neighbor list is used to make this calculation
faster, this neighbor list is updated every 100 steps.
BEGIN_PLUMED_FILE
COORDINATION GROUPA=1-10 GROUPB=20-100 R_0=0.3 NLIST NL_CUTOFF=0.5 NL_STRIDE=100
The following is a dummy example which should compute the value 0 because the self interaction of atom 1 is
skipped. Notice that in plumed 2.0 "self interactions" were not skipped, and the same calculation should return 1.
BEGIN_PLUMED_FILE
c: COORDINATION GROUPA=1 GROUPB=1 R_0=0.3
PRINT ARG=c STRIDE=10
Here's an example that shows what happens when providing COORDINATION with a single group:
BEGIN_PLUMED_FILE
# define some huge group:
group: GROUP ATOMS=1-1000
# Here’s coordination of a group against itself:
c1: COORDINATION GROUPA=group GROUPB=group R_0=0.3
# Here’s coordination within a single group:
x: COORDINATION GROUPA=group R_0=0.3
# This is just multiplying times 2 the variable x:
c2: COMBINE ARG=x COEFFICIENTS=2
# the two variables c1 and c2 should be identical, but the calculation of c2 is twice faster
# since it runs on half of the pairs.
PRINT ARG=c1,c2 STRIDE=10
5.2.10
DHENERGY
This is part of the colvar module
Calculate Debye-Huckel interaction energy among GROUPA and GROUPB.
This variable calculates the electrostatic interaction among GROUPA and GROUPB using a Debye-Huckel approximation defined as
1 XX
e−κ|rij |
qi qj
4πr 0
|rij |
i∈A j∈B
This collective variable can be used to analyze or induce electrostatically driven reactions [8]. Notice that the value
of the DHENERGY is returned in plumed units (see UNITS).
Generated by Doxygen
94
Collective Variables
If GROUPB is empty, it will sum the N∗(N-1)/2 pairs in GROUPA. This avoids computing twice permuted indexes
(e.g. pair (i,j) and (j,i)) thus running at twice the speed.
Notice that if there are common atoms between GROUPA and GROUPB their interaction is discarded.
The atoms involved can be specified using
GROUPA
First list of atoms.
For more information on how to specify lists of atoms see
Groups and Virtual Atoms
GROUPB
Second list of atoms (if empty, N∗(N-1)/2 pairs in GROUPA are counted). For more information on
how to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
I
( default=1.0 ) Ionic strength (M)
TEMP
( default=300.0 ) Simulation temperature (K)
EPSILON
( default=80.0 ) Dielectric constant of solvent
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Perform the calculation in serial - for debug purpose
SERIAL
PAIR
( default=off ) Pair only 1st element of the 1st group with 1st element in the
second, etc
NLIST
( default=off ) Use a neighbor list to speed up the calculation
NL_CUTOFF
The cutoff for the neighbor list
NL_STRIDE
The frequency with which we are updating the atoms in the neighbor list
Examples
BEGIN_PLUMED_FILE
# this is printing the electrostatic interaction between two groups of atoms
dh: DHENERGY GROUPA=1-10 GROUPB=11-20 EPSILON=80.0 I=0.1 TEMP=300.0
PRINT ARG=dh
5.2.11
DIHCOR
This is part of the multicolvar module
Measures the degree of similarity between dihedral angles.
Generated by Doxygen
5.2 CV Documentation
95
This colvar calculates the following quantity.
s=
1X
[1 + cos(φi − ψi )]
2 i
where the φi and ψ values and the instantaneous values for the TORSION angles of interest.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the dihedral correlation values you wish to calculate. Keywords like
ATOMS1, ATOMS2, ATOMS3,... should be listed and one dihedral correlation will be calculated
for each ATOM keyword you specify (all ATOM keywords should specify the indices of 8 atoms).
The eventual number of quantities calculated by this action will depend on what functions of the
distribution you choose to calculate. You can use multiple instances of this keyword i.e. ATOMS1,
ATOMS2, ATOMS3...
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Examples
The following provides an example input for the DIHCOR action
BEGIN_PLUMED_FILE
DIHCOR ...
ATOMS1=1,2,3,4,5,6,7,8
ATOMS2=5,6,7,8,9,10,11,12
LABEL=dih
... DIHCOR
PRINT ARG=dih FILE=colvar STRIDE=10
In the above input we are calculating the correlation between the torsion angle involving atoms 1, 2, 3 and 4 and the
torsion angle involving atoms 5, 6, 7 and 8. This is then added to the correlation between the torsion angle involving
atoms 5, 6, 7 and 8 and the correlation angle involving atoms 9, 10, 11 and 12.
Writing out the atoms involved in all the torsion angles in this way can be rather tedious. Thankfully if you are working
with protein you can avoid this by using the MOLINFO command. PLUMED uses the pdb file that you provide to
this command to learn about the topology of the protein molecule. This means that you can specify torsion angles
using the following syntax:
Generated by Doxygen
96
Collective Variables
BEGIN_PLUMED_FILE
MOLINFO MOLTYPE=protein STRUCTURE=myprotein.pdb
DIHCOR ...
ATOMS1=@phi-3,@psi-3
ATOMS2=@psi-3,@phi-4
ATOMS4=@phi-4,@psi-4
... DIHCOR
PRINT ARG=dih FILE=colvar STRIDE=10
Here, @phi-3 tells plumed that you would like to calculate the φ angle in the third residue of the protein. Similarly
@psi-4 tells plumed that you want to calculate the ψ angle of the fourth residue of the protein.
5.2.12
DIMER
This is part of the colvar module
This CV computes the dimer interaction energy for a collection of dimers.
Each dimer represents an atom, as described in the dimer paper [9]. A system of N atoms is thus represented with
N dimers, each Dimer being composed of two beads and eventually a virtual site representing its center of mass.
A typical configuration for a dimerized system has the following ordering of atoms:
1 TAG1 X Y Z N atoms representing the first bead of each Dimer
2 TAG2 X Y Z
...
N TAGN X Y Z N atoms representing the second bead of each Dimer
N+1 TAG1 X Y Z
N+2 TAG2 X Y Z
...
2N TAGN X Y Z Optional: N atoms representing the center of mass of each Dimer
2N+1 TAG1 X Y Z
2N+2 TAG2 X Y Z
...
3N TAGN X Y Z The configuration might go on with un-dimerized atoms (like a solvent)
3N+1
3N+2
...
The Dimer interaction energy is defined between atoms x and N+x, for x=1,...,N and is characterized by two parameters Q and DSIGMA. These are passed as mandatory arguments along with the temperature of the system.
The atoms involved can be specified using
Generated by Doxygen
5.2 CV Documentation
97
ATOMS1
The list of atoms representing the first bead of each Dimer being considered by this CV. Used
if ALLATOMS flag is missing. For more information on how to specify lists of atoms see
Groups and Virtual Atoms
ATOMS2
The list of atoms representing the second bead of each Dimer being considered by this CV.
Used if ALLATOMS flag is missing. For more information on how to specify lists of atoms see
Groups and Virtual Atoms
Compulsory keywords
DSIGMA
The interaction strength of the dimer bond.
Q
The exponent of the dimer potential.
TEMP
The temperature (in Kelvin) of the simulation.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Use EVERY atom of the system. Overrides ATOMS keyword.
ALLATOMS
NOVSITES
( default=off ) If present the configuration is without virtual sites at the centroid
positions.
Examples
This line tells Plumed to compute the Dimer interaction energy for every dimer in the system.
BEGIN_PLUMED_FILE
dim: DIMER TEMP=300 Q=0.5 ALLATOMS DSIGMA=0.002
If the simulation doesn't use virtual sites for the dimers centers of mass, Plumed has to know in order to determine
correctly the total number of dimers from the total number of atoms:
BEGIN_PLUMED_FILE
dim: DIMER TEMP=300 Q=0.5 ALLATOMS DSIGMA=0.002 NOVSITES
The NOVSITES flag is not required if one provides the atom serials of each Dimer. These are defined through two
lists of atoms provided instead of the ALLATOMS keyword. For example, the Dimer interaction energy of dimers
specified by beads (1;23),(5;27),(7;29) is:
BEGIN_PLUMED_FILE
dim: DIMER TEMP=300 Q=0.5 ATOMS1=1,5,7 ATOMS2=23,27,29 DSIGMA=0.002
Note that the ATOMS1,ATOMS2 keywords can support atom groups and interval notation as defined in GROUP.
In a Replica Exchange simulation the keyword DSIGMA can be used in two ways: if a plumed.n.dat file is provided
for each replica, then DSIGMA is passed as a single value, like in the previous examples, and each replica will read
its own DSIGMA value. If a unique plumed.dat is given, DSIGMA has to be a list containing a value for each replica.
For 4 replicas:
Generated by Doxygen
98
Collective Variables
BEGIN_PLUMED_FILE
dim: DIMER TEMP=300 Q=0.5 ATOMS1=1,5,7 ATOMS2=23,27,29 DSIGMA=0.002,0.002,0.004,0.01
Usage of the CV
The dimer interaction is not coded in the driver program and has to be inserted in the Hamiltonian of the system as
a linear RESTRAINT (see RESTRAINT):
BEGIN_PLUMED_FILE
dim: DIMER TEMP=300 Q=0.5 ALLATOMS DSIGMA=0.002
RESTRAINT ARG=dim AT=0 KAPPA=0 SLOPE=1 LABEL=dimforces
In a replica exchange, Metadynamics (see METAD) can be used on the Dimer CV to reduce the number of replicas.
Just keep in mind that METAD SIGMA values should be tuned in the standard way for each replica according to the
value of DSIGMA.
5.2.13
DIPOLE
This is part of the colvar module
Calculate the dipole moment for a group of atoms.
When running with periodic boundary conditions, the atoms should be in the proper periodic image. This is done
automatically since PLUMED 2.5, by considering the ordered list of atoms and rebuilding the molecule with a
procedure that is equivalent to that done in WHOLEMOLECULES . Notice that rebuilding is local to this action. This
is different from WHOLEMOLECULES which actually modifies the coordinates stored in PLUMED.
In case you want to recover the old behavior you should use the NOPBC flag. In that case you need to take care
that atoms are in the correct periodic image.
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Keyword
Description
x
COMPONENTS
the x-component of the dipole
y
COMPONENTS
the y-component of the dipole
z
COMPONENTS
the z-component of the dipole
The atoms involved can be specified using
GROUP
the group of atoms we are calculating the dipole moment for. For more information on how to specify
lists of atoms see Groups and Virtual Atoms
Generated by Doxygen
5.2 CV Documentation
99
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) calculate the x, y and z components of the dipole separately and
store them as label.x, label.y and label.z
COMPONENTS
Examples
The following tells plumed to calculate the dipole of the group of atoms containing the atoms from 1-10 and print it
every 5 steps
BEGIN_PLUMED_FILE
d: DIPOLE GROUP=1-10
PRINT FILE=output STRIDE=5 ARG=5
Attention
If the total charge Q of the group in non zero, then a charge Q/N will be subtracted to every atom, where N
is the number of atoms. This implies that the dipole (which for a charged system depends on the position) is
computed on the geometric center of the group.
5.2.14
DISTANCE_FROM_CONTOUR
This is part of the multicolvar module
Calculate the perpendicular distance from a Willard-Chandler dividing surface.
Suppose that you have calculated a multicolvar. By doing so you have calculated a set of colvars, si , and each of
these colvars has a well defined position in space (xi , yi , zi ). You can use this information to calculate a phase-field
model of the colvar density using:
p(x, y, x) =
X
i
si K
x − xi y − yi z − zi
,
,
σx
σy
σz
In this expression σx , σy and σz are bandwidth parameters and K is one of the kernelfunctions. This is what is
done within MULTICOLVARDENS
The Willard-Chandler surface is a surface of constant density in the above phase field p(x, y, z). In other words, it
is a set of points, (x0 , y 0 , z 0 ), in your box which have:
p(x0 , y 0 , z 0 ) = ρ
where ρ is some target density. This action calculates the distance projected on the x, y or z axis between the
position of some test particle and this surface of constant field density.
Generated by Doxygen
100
Collective Variables
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Description
dist1
dist2
qdist
the distance between the reference atom and the nearest contour
the distance between the reference atom and the other contour
the differentiable (squared) distance between the two contours (see above)
thickness
the distance between the two contours on the line from the reference atom
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
Generated by Doxygen
5.2 CV Documentation
101
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The atoms involved can be specified using
ATOM
The atom whose perpendicular distance we are calculating from the contour. For more information on
how to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
DATA
The input base multicolvar which is being used to calculate the contour
BANDWIDTH
the bandwidths for kernel density estimation
KERNEL
( default=gaussian ) the kernel function you are using. More details on the kernels available in
plumed plumed can be found in kernelfunctions.
DIR
the direction perpendicular to the contour that you are looking for
CONTOUR
TOLERANCE
the value we would like for the contour
( default=0.1 ) this parameter is used to manage periodic boundary conditions. The problem
here is that we can be between contours even when we are not within the membrane because
of periodic boundary conditions. When we are in the contour, however, we should have it so
that the sums of the absolute values of the distances to the two contours is approximately
the distance between the two contours. There can be numerical errors in these calculations,
however, so we specify a small tolerance here
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Examples
In this example atoms 2-100 are assumed to be concentrated along some part of the z axis so that you an interface
between a liquid/solid and the vapor. The quantity dc measures the distance between the surface at which the
density of 2-100 atoms is equal to 0.2 and the position of the test particle atom 1.
BEGIN_PLUMED_FILE
dens: DENSITY SPECIES=2-100
dc: DISTANCE_FROM_CONTOUR DATA=dens ATOM=1 BANDWIDTH=0.5,0.5,0.5 DIR=z CONTOUR=0.2
Generated by Doxygen
102
5.2.15
Collective Variables
DISTANCE
This is part of the colvar module
Calculate the distance between a pair of atoms.
By default the distance is computed taking into account periodic boundary conditions. This behavior can be changed
with the NOPBC flag. Moreover, single components in Cartesian space (x,y, and z, with COMPONENTS) or single
components projected to the three lattice vectors (a,b, and c, with SCALED_COMPONENTS) can be also computed.
Notice that Cartesian components will not have the proper periodicity! If you have to study e.g. the permeation of a
molecule across a membrane, better to use SCALED_COMPONENTS.
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Keyword
Description
x
COMPONENTS
the x-component of the vector connecting the two atoms
y
COMPONENTS
the y-component of the vector connecting the two atoms
z
COMPONENTS
the z-component of the vector connecting the two atoms
a
SCALED_COMPONENTS
the normalized projection on the first lattice vector of the vector connecting the two atoms
b
SCALED_COMPONENTS
the normalized projection on the second lattice vector of the vector
connecting the two atoms
c
SCALED_COMPONENTS
the normalized projection on the third lattice vector of the vector connecting the two atoms
The atoms involved can be specified using
ATOMS
the pair of atom that we are calculating the distance between. For more information on how to specify
lists of atoms see Groups and Virtual Atoms
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) calculate the x, y and z components of the distance separately
and store them as label.x, label.y and label.z
COMPONENTS
SCALED_COMPONENTS
( default=off ) calculate the a, b and c scaled components of the distance separately and store them as label.a, label.b and label.c
Generated by Doxygen
5.2 CV Documentation
103
Examples
The following input tells plumed to print the distance between atoms 3 and 5, the distance between atoms 2 and 4
and the x component of the distance between atoms 2 and 4.
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=3,5
d2: DISTANCE ATOMS=2,4
d2c: DISTANCE ATOMS=2,4 COMPONENTS
PRINT ARG=d1,d2,d2c.x
The following input computes the end-to-end distance for a polymer of 100 atoms and keeps it at a value around 5.
BEGIN_PLUMED_FILE
WHOLEMOLECULES ENTITY0=1-100
e2e: DISTANCE ATOMS=1,100 NOPBC
RESTRAINT ARG=e2e KAPPA=1 AT=5
Notice that NOPBC is used to be sure that if the end-to-end distance is larger than half the simulation box the
distance is compute properly. Also notice that, since many MD codes break molecules across cell boundary, it
might be necessary to use the WHOLEMOLECULES keyword (also notice that it should be before distance). The
list of atoms provided to WHOLEMOLECULES here contains all the atoms between 1 and 100. Strictly speaking,
this is not necessary. If you know for sure that atoms with difference in the index say equal to 10 are not going to be
farther than half cell you can e.g. use
BEGIN_PLUMED_FILE
WHOLEMOLECULES ENTITY0=1,10,20,30,40,50,60,70,80,90,100
e2e: DISTANCE ATOMS=1,100 NOPBC
RESTRAINT ARG=e2e KAPPA=1 AT=5
Just be sure that the ordered list provide to WHOLEMOLECULES has the following properties:
• Consecutive atoms should be closer than half-cell throughout the entire simulation.
• Atoms required later for the distance (e.g. 1 and 100) should be included in the list
The following example shows how to take into account periodicity e.g. in z-component of a distance
BEGIN_PLUMED_FILE
# this is a center of mass of a large group
c: COM ATOMS=1-100
# this is the distance between atom 101 and the group
d: DISTANCE ATOMS=c,101 COMPONENTS
# this makes a new variable, dd, equal to d and periodic, with domain -10,10
# this is the right choise if e.g. the cell is orthorombic and its size in
# z direction is 20.
dz: COMBINE ARG=d.z PERIODIC=-10,10
# metadynamics on dd
METAD ARG=dz SIGMA=0.1 HEIGHT=0.1 PACE=200
Using SCALED_COMPONENTS this problem should not arise because they are always periodic with domain (-0.←5,+0.5).
5.2.16
EEFSOLV
Generated by Doxygen
104
Collective Variables
This is part of the colvar module
Calculates EEF1 solvation free energy for a group of atoms.
EEF1 is a solvent-accessible surface area based model, where the free energy of solvation is computed using a
pairwise interaction term for non-hydrogen atoms:
∆Gsolv
= ∆Gref
i
i −
X
fi (rij )Vj
j6=i
where ∆Gsolv
is the free energy of solvation, ∆Gref
i
i is the reference solvation free energy, Vj is the volume of atom
j and
(r − Ri )2
2 ∆Gfree
i
exp −
fi (r)4πr2 = √
λ2i
π λi
where ∆Gfree
is the solvation free energy of the isolated group, λi is the correlation length equal to the width of the
i
first solvation shell and Ri is the van der Waals radius of atom i.
The output from this collective variable, the free energy of solvation, can be used with the BIASVALUE keyword to
provide implicit solvation to a system. All parameters are designed to be used with a modified CHARMM36 force
field. It takes only non-hydrogen atoms as input, these can be conveniently specified using the GROUP action
with the NDX_GROUP parameter. To speed up the calculation, EEFSOLV internally uses a neighbor list with a
cutoff dependent on the type of atom (maximum of 1.95 nm). This cutoff can be extended further by using the
NL_BUFFER keyword.
The atoms involved can be specified using
ATOMS
The atoms to be included in the calculation, e.g. the whole protein.. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
NL_BUFFER
The buffer to the intrinsic cutoff used when calculating pairwise interactions.
NL_STRIDE
The frequency with which the neighbor list is updated.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Correct free energy of solvation constants for temperatures different from 298.15 K
TEMP_CORRECTION
Examples
Generated by Doxygen
5.2 CV Documentation
105
BEGIN_PLUMED_FILE
MOLINFO MOLTYPE=protein STRUCTURE=peptide.pdb
WHOLEMOLECULES ENTITY0=1-111
# This allows us to select only non-hydrogen atoms
protein-h: GROUP NDX_FILE=index.ndx NDX_GROUP=Protein-H
# We extend the cutoff by 0.2 nm and update the neighbor list every 10 steps
solv: EEFSOLV ATOMS=protein-h NL_STRIDE=10 NL_BUFFER=0.2
# Here we actually add our calculated energy back to the potential
bias: BIASVALUE ARG=solv
PRINT ARG=solv FILE=SOLV
5.2.17
ENERGY
This is part of the colvar module
Calculate the total energy of the simulation box.
Total energy can be biased with umbrella sampling [10] or with well tempered metadynamics [11].
Notice that this CV could be unavailable with some MD code. When it is available, and when also replica exchange
is available, metadynamics applied to ENERGY can be used to decrease the number of required replicas.
Bug Acceptance for replica exchange when ENERGY is biased is computed correctly only of all the replicas has
the same potential energy function. This is for instance not true when using GROMACS with lambda replica
exchange of with plumed-hrex branch.
Examples
The following input instructs plumed to print the energy of the system
BEGIN_PLUMED_FILE
ene: ENERGY
PRINT ARG=ene
5.2.18
ERMSD
This is part of the colvar module
Calculate eRMSD with respect to a reference structure.
eRMSD is a metric developed for measuring distances between three-dimensional RNA structures. The standard
RMSD measure is highly inaccurate when measuring distances among three-dimensional structures of nucleic
acids. It is not unusual, for example, that two RNA structures with low RMSD (i.e. less than 0.4nm) display a
completely different network of base-base interactions.
eRMSD measures the distance between structures by considering only the relative positions and orientations of
nucleobases. The eRMSD can be considered as a vectorial version of contact maps and it is calculated as follows:
Generated by Doxygen
106
Collective Variables
1. Set up a local reference system in the center of the six-membered ring of each nucleobase in a molecule.
The xy plane lies on the plane of the nucleobase, and it is oriented such that the Watson-Crick interaction is
always at θ ≈ 60◦ .
2. Calculate all pairwise distance vectors ~
ri,j among base centers.
˜ri,j = (rx /a, ry /a, rz /b), where a=b=5 , c=3 . This rescaling has the effect of
3. Rescale distance vectors as ~
weighting more deviations on the z-axis with respect to the x/y directions.
4. Calculate the G vectors
~ ~˜r) = (sin(γ r̃)r̃x /r̃, sin(γ r̃)r̃y /r̃, sin(γ r̃)r̃z /r̃, 1 + cos(γ r̃)) × Θ(r̃cutof f − r̃)
G(
γ
Here, γ = π/r̃cutof f and Θ is the Heaviside step function. The default cutoff is set to 2.4.
1. The eRMSD between two structures α and β reads
s
eRM SD =
1 X ~ ˜α
~ ~˜rβjk )|2
|G(~rjk ) − G(
N
j,k
Using the default cutoff, two structures with eRMSD of 0.7 or lower can be considered as significantly similar. A full
description of the eRMSD can be found in [12]
ERMSD is computed using the position of three atoms on the 6-membered ring of each involved nucleobase. The
atoms should be:
• C2,C4,C6 for pyrimdines
• C2,C6,C4 for purines
The different order for purines and pyrimidines is fundamental and allows you to compute ERMSD between structures with different sequences as well! Notice that the simplest way to avoid mistakes in choosing these atoms is to
use the @lcs-# strings as shown in the examples (see also MOLINFO).
Warning
Notice that the ERMSD implemented here is not integrated with the other metrics in plumed. As a consequence, it is not (yet) possible to e.g. build path collective variables using ERMSD
Notice that ERMSD expect a single molecule and makes coordinate whole before anything else. As such,
results might be unexpected for a multi molecular system.
The atoms involved can be specified using
ATOMS
the list of atoms (use lcs).
Groups and Virtual Atoms
For more information on how to specify lists of atoms see
Compulsory keywords
Generated by Doxygen
5.2 CV Documentation
107
REFERENCE
a file in pdb format containing the reference structure and the atoms involved in the CV.
CUTOFF
( default=2.4 ) only pairs of atoms closer than CUTOFF are considered in the calculation.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
PAIRS
List of pairs considered. All pairs are considered if this value is not specified.
Examples
Calculate the eRMSD from reference structure reference.pdb using the default cutoff (2.4). The list of residues
involved in the calculation has to be specified. In this example, the eRMSD is calculated considering residues
1,2,3,4,5,6.
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=reference.pdb
eRMSD1: ERMSD REFERENCE=reference.pdb ATOMS=@lcs-1,@lcs-2,@lcs-3,@lcs-4,@lcs-5,@lcs-6
5.2.19
EXTRACV
This is part of the colvar module
XX
Compulsory keywords
NAME
name of the CV as computed by the MD engine
Examples
XX
5.2.20
FAKE
This is part of the colvar module
Generated by Doxygen
108
Collective Variables
This is a fake colvar container used by cltools or various other actions that supports input and period definitions
The atoms involved can be specified using
ATOMS
the fake atom index, a number is enough. For more information on how to specify lists of atoms see
Groups and Virtual Atoms
Compulsory keywords
PERIODIC
if the output of your function is periodic then you should specify the periodicity of the function. If the output is not periodic you must state this using PERIODIC=NO,NO (one for the
lower and the other for the upper boundary). For multicomponents then it is PERIOD←IC=mincomp1,maxcomp1,mincomp2,maxcomp2 etc
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
COMPONENTS
additional components that this variable is supposed to have. Periodicity is
ruled by PERIODIC keyword
Examples
BEGIN_PLUMED_FILE
FAKE ATOMS=1 PERIODIC=-3.14,3.14
5.2.21
LABEL=d2
GPROPERTYMAP
This is part of the mapping module
Property maps but with a more flexible framework for the distance metric being used.
This colvar calculates a property map using the formalism developed by Spiwok [13]. In essence if you have the
value of some property, Xi , that it takes at a set of high-dimensional positions then you calculate the value of the
property at some arbitrary point in the high-dimensional space using:
P
i Xi ∗ exp(−λDi (x))
X= P
i exp(−λDi (x))
Within PLUMED there are multiple ways to define the distance from a high-dimensional configuration, Di . You could
calculate the RMSD distance or you could calculate the amount by which a set of collective variables change. As
Generated by Doxygen
5.2 CV Documentation
109
such this implementation of the property map allows one to use all the different distance metric that are discussed
in Distances from reference configurations. This is as opposed to the alternative implementation PROPERTYMAP
which is a bit faster but which only allows one to use the RMSD distance.
Compulsory keywords
REFERENCE
a pdb file containing the set of reference configurations
PROPERTY
the property to be used in the index. This should be in the REMARK of the reference
TYPE
( default=OPTIMAL-FAST ) the manner in which distances are calculated. More information on
the different metrics that are available in PLUMED can be found in the section of the manual on
Distances from reference configurations
LAMBDA
( default=0 ) the value of the lambda parameter for paths
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
DISABLE_CHECKS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) disable checks on reference input structures.
NOZPATH
( default=off ) do not calculate the zpath position
NOMAPPING
( default=off ) do not calculate the position on the manifold
Examples
The input shown below can be used to calculate the interpolated values of two properties called X and Y based on
the values that these properties take at a set of reference configurations and using the formula above. For this input
the distances between the reference configurations and the instantaneous configurations are calculated using the
OPTIMAL metric that is discussed at length in the manual pages on RMSD.
BEGIN_PLUMED_FILE
p2: GPROPERTYMAP REFERENCE=allv.pdb PROPERTY=X,Y LAMBDA=69087
PRINT ARG=p2.X,p2.Y,p2.zpath STRIDE=1 FILE=colvar
The additional input file for this calculation, which contains the reference frames and the values of X and Y at these
reference points has the following format.
REMARK X=1 Y=2
ATOM
1 CL
ATOM
5 CLP
ATOM
6 OL
ATOM
7 NL
ATOM
8 HL
ATOM
9 CA
ATOM
10 HA
ATOM
11 CB
Generated by Doxygen
ALA
ALA
ALA
ALA
ALA
ALA
ALA
ALA
1
1
1
1
1
1
1
1
-3.171
-1.819
-1.177
-1.313
-1.845
-0.003
0.205
0.009
0.295
-0.143
-0.889
0.341
0.961
-0.019
-1.051
0.135
2.045
1.679
2.401
0.529
-0.011
0.021
0.259
-1.509
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
110
Collective Variables
ATOM
15 CRP
ATOM
16 OR
ATOM
17 NR
ATOM
18 HR
ATOM
19 CR
END
FIXED
REMARK X=2 Y=3
ATOM
1 CL
ATOM
5 CLP
ATOM
6 OL
ATOM
7 NL
ATOM
8 HL
ATOM
9 CA
ATOM
10 HA
ATOM
11 CB
ATOM
15 CRP
ATOM
16 OR
ATOM
17 NR
ATOM
18 HR
ATOM
19 CR
END
5.2.22
ALA
ALA
ALA
ALA
ALA
1
1
1
1
1
1.121
1.723
1.423
0.873
2.477
0.799
1.669
0.519
-0.161
1.187
0.663
0.043
1.941
2.413
2.675
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
ALA
ALA
ALA
ALA
ALA
ALA
ALA
ALA
ALA
ALA
ALA
ALA
ALA
1
1
1
1
1
1
1
1
1
1
1
1
1
-3.175
-1.814
-1.201
-1.296
-1.807
0.009
0.175
0.027
1.149
1.835
1.380
0.764
2.431
0.365
-0.106
-0.849
0.337
0.951
-0.067
-1.105
0.046
0.725
1.491
0.537
-0.060
1.195
2.024
1.685
2.425
0.534
-0.044
0.033
0.283
-1.501
0.654
-0.011
1.968
2.461
2.683
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
GYRATION
This is part of the colvar module
Calculate the radius of gyration, or other properties related to it.
The different properties can be calculated and selected by the TYPE keyword: the Radius of Gyration (RADIUS);
the Trace of the Gyration Tensor (TRACE); the Largest Principal Moment of the Gyration Tensor (GTPC_1); the
middle Principal Moment of the Gyration Tensor (GTPC_2); the Smallest Principal Moment of the Gyration Tensor
(GTPC_3); the Asphericiry (ASPHERICITY); the Acylindricity (ACYLINDRICITY); the Relative Shape Anisotropy
(KAPPA2); the Smallest Principal Radius Of Gyration (GYRATION_3); the Middle Principal Radius of Gyration (G←YRATION_2); the Largest Principal Radius of Gyration (GYRATION_1). A derivation of all these different variants
can be found in [14]
The radius of gyration is calculated using:
sGyr
Pn m |r − r
|2 1/2
i i
i
Pn COM
=
i mi
with the position of the center of mass rCOM given by:
rCOM
Pn
i ri mi
= P
n
i mi
The radius of gyration usually makes sense when atoms used for the calculation are all part of the same molecule.
When running with periodic boundary conditions, the atoms should be in the proper periodic image. This is done
automatically since PLUMED 2.2, by considering the ordered list of atoms and rebuilding the broken entities using
a procedure that is equivalent to that done in WHOLEMOLECULES . Notice that rebuilding is local to this action.
This is different from WHOLEMOLECULES which actually modifies the coordinates stored in PLUMED.
In case you want to recover the old behavior you should use the NOPBC flag. In that case you need to take care
that atoms are in the correct periodic image.
The atoms involved can be specified using
Generated by Doxygen
5.2 CV Documentation
ATOMS
111
the group of atoms that you are calculating the Gyration Tensor for. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
TYPE
( default=RADIUS ) The type of calculation relative to the Gyration Tensor you want to perform
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
MASS_WEIGHTED
( default=off ) set the masses of all the atoms equal to one
Examples
The following input tells plumed to print the radius of gyration of the chain containing atoms 10 to 20.
BEGIN_PLUMED_FILE
GYRATION TYPE=RADIUS ATOMS=10-20 LABEL=rg
PRINT ARG=rg STRIDE=1 FILE=colvar
5.2.23
PARABETARMSD
This is part of the secondarystructure module
Probe the parallel beta sheet content of your protein structure.
Two protein segments containing three contiguous residues can form a parallel beta sheet. Although if the two
segments are part of the same protein chain they must be separated by a minimum of 3 residues to make room for
the turn. This colvar thus generates the set of all possible six residue sections that could conceivably form a parallel
beta sheet and calculates the RMSD distance between the configuration in which the residues find themselves
and an idealized parallel beta sheet structure. These distances can be calculated by either aligning the instantaneous structure with the reference structure and measuring each atomic displacement or by calculating differences
between the set of inter-atomic distances in the reference and instantaneous structures.
This colvar is based on the following reference [6]. The authors of this paper use the set of distances from the
parallel beta sheet configurations to measure the number of segments whose configuration resembles a parallel
beta sheet. This is done by calculating the following sum of functions of the rmsd distances:
s=
X 1−
ri −d0
r0
1−
ri −d0
r0
i
Generated by Doxygen
n
m
112
Collective Variables
where the sum runs over all possible segments of parallel beta sheet. By default the NN, MM and D_0 parameters
are set equal to those used in [6]. The R_0 parameter must be set by the user - the value used in [6] was 0.08 nm.
If you change the function in the above sum you can calculate quantities such as the average distance from a
structure composed of only parallel beta sheets or the distance between the set of residues that is closest to a
parallel beta sheet and the reference configuration. To do these sorts of calculations you can use the AVERAGE
and MIN keywords. In addition you can use the LESS_THAN keyword if you would like to change the form of the
switching function. If you use any of these options you no longer need to specify NN, R_0, MM and D_0.
Please be aware that for codes like gromacs you must ensure that plumed reconstructs the chains involved in your
CV when you calculate this CV using anything other than TYPE=DRMSD. For more details as to how to do this see
WHOLEMOLECULES.
Description of components
By default this Action calculates the number of structural units that are within a certain distance of a idealized
secondary structure element. This quantity can then be referenced elsewhere in the input by using the label of
the action. However, this Action can also be used to calculate the following quantities by using the keywords as
described below. The quantities then calculated can be referenced using the label of the action followed by a dot
and then the name from the table below. Please note that you can use the LESS_THAN keyword more than once.
The resulting components will be labelled label.lessthan-1, label.lessthan-2 and so on unless you exploit the fact
that these labels can be given custom labels by using the LABEL keyword in the description of you LESS_THAN
function that you are computing
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
The atoms involved can be specified using
RESIDUES
this command is used to specify the set of residues that could conceivably form part of the secondary structure. It is possible to use residues numbers as the various chains and residues
should have been identified else using an instance of the MOLINFO action. If you wish to use all
the residues from all the chains in your system you can do so by specifying all. Alternatively, if you
wish to use a subset of the residues you can specify the particular residues you are interested in
as a list of numbers. Please be aware that to form secondary structure elements your chain must
contain at least N residues, where N is dependent on the particular secondary structure you are
interested in. As such if you define portions of the chain with fewer than N residues the code will
crash.
Compulsory keywords
Generated by Doxygen
5.2 CV Documentation
TYPE
113
R_0
( default=DRMSD ) the manner in which RMSD alignment is performed. Should be OPTIMAL, S←IMPLE or DRMSD. For more details on the OPTIMAL and SIMPLE methods see RMSD. For more
details on the DRMSD method see DRMSD.
( default=0.08 ) The r_0 parameter of the switching function.
D_0
( default=0.0 ) The d_0 parameter of the switching function
NN
( default=8 ) The n parameter of the switching function
MM
( default=12 ) The m parameter of the switching function
STYLE
( default=all ) Parallel beta sheets can either form in a single chain or from a pair of chains. If S←TYLE=all all chain configuration with the appropriate geometry are counted. If STYLE=inter only
sheet-like configurations involving two chains are counted, while if STYLE=intra only sheet-like configurations involving a single chain are counted
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions
VERBOSE
( default=off ) write a more detailed output
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
LESS_THAN
calculate the number of variables less than a certain target value. This quanP
tity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
MIN
ALT_MIN
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
STRANDS_CUTOFF
If in a segment of protein the two strands are further apart then the calculation
of the actual RMSD is skipped as the structure is very far from being beta-sheet
like. This keyword speeds up the calculation enormously when you are using
the LESS_THAN option. However, if you are using some other option, then this
cannot be used
Generated by Doxygen
114
Collective Variables
Examples
The following input calculates the number of six residue segments of protein that are in an parallel beta sheet
configuration.
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=beta.pdb
pb: PARABETARMSD RESIDUES=all STRANDS_CUTOFF=1
Here the same is done use RMSD instead of DRMSD
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=helix.pdb
WHOLEMOLECULES ENTITY0=1-100
hh: PARABETARMSD RESIDUES=all TYPE=OPTIMAL R_0=0.1
5.2.24
STRANDS_CUTOFF=1
PATHMSD
This is part of the colvar module
This Colvar calculates path collective variables.
This is the Path Collective Variables implementation ( see [5] ). This variable computes the progress along a given
set of frames that is provided in input ("sss" component) and the distance from them ("zzz" component). (see
below).
When running with periodic boundary conditions, the atoms should be in the proper periodic image. This is done
automatically since PLUMED 2.5, by considering the ordered list of atoms and rebuilding molecules with a procedure
that is equivalent to that done in WHOLEMOLECULES . Notice that rebuilding is local to this action. This is different
from WHOLEMOLECULES which actually modifies the coordinates stored in PLUMED.
In case you want to recover the old behavior you should use the NOPBC flag. In that case you need to take care
that atoms are in the correct periodic image.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
sss
the position on the path
zzz
the distance from the path
Compulsory keywords
Generated by Doxygen
5.2 CV Documentation
115
LAMBDA
the lambda parameter is needed for smoothing, is in the units of plumed
REFERENCE
the pdb is needed to provide the various milestones
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
NEIGH_SIZE
size of the neighbor list
NEIGH_STRIDE
how often the neighbor list needs to be calculated in time units
EPSILON
(default=-1) the maximum distance between the close and the current structure,
the positive value turn on the close structure method
LOG_CLOSE
(default=0) value 1 enables logging regarding the close structure
DEBUG_CLOSE
(default=0) value 1 enables extensive debugging info regarding the close structure, the simulation will run much slower
Examples
Here below is a case where you have defined three frames and you want to calculate the progress along the path
and the distance from it in p1
BEGIN_PLUMED_FILE
p1: PATHMSD REFERENCE=file.pdb LAMBDA=500.0 NEIGH_STRIDE=4 NEIGH_SIZE=8
PRINT ARG=p1.sss,p1.zzz STRIDE=1 FILE=colvar FMT=%8.4f
note that NEIGH_STRIDE=4 NEIGH_SIZE=8 control the neighbor list parameter (optional but recommended for
performance) and states that the neighbor list will be calculated every 4 steps and consider only the closest 8
member to the actual md snapshots.
In the REFERENCE PDB file the frames must be separated either using END or ENDMDL.
Note
The implementation of this collective variable and of PROPERTYMAP is shared, as well as most input options.
5.2.25
PATH
This is part of the mapping module
Path collective variables with a more flexible framework for the distance metric being used.
The Path Collective Variables developed by Branduardi and co-workers [5] allow one to compute the progress
along a high-dimensional path and the distance from the high-dimensional path. The progress along the path (s) is
computed using:
Generated by Doxygen
116
Collective Variables
PN
s = Pi=1
N
i exp(−λR[X − Xi ])
i=1
exp(−λR[X − Xi ])
while the distance from the path (z) is measured using:
"N
#
X
1
z = − ln
exp(−λR[X − Xi ])
λ
i=1
In these expressions N high-dimensional frames ( Xi ) are used to describe the path in the high-dimensional space.
The two expressions above are then functions of the distances from each of the high-dimensional frames R[X −Xi ].
Within PLUMED there are multiple ways to define the distance from a high-dimensional configuration. You could
calculate the RMSD distance or you could calculate the amount by which a set of collective variables change. As
such this implementation of the path CV allows one to use all the difference distance metrics that are discussed in
Distances from reference configurations. This is as opposed to the alternative implementation of path (PATHMSD)
which is a bit faster but which only allows one to use the RMSD distance.
The s and z variables are calculated using the above formulas by default. However, there is an alternative method
of calculating these collective variables, which is detailed in [15]. This alternative method uses the tools of geometry
(as opposed to algebra, which is used in the equations above). In this alternative formula the progress along the
path s is calculated using:
s = i2 + sign(i2 − i1 )
p
(v1 · v2 )2 − |v3 |2 (|v1 |2 − |v2 |2 ) v1 · v3 − |v3 |2
−
2|v3 |2
2|v3 |2
where v1 and v3 are the vectors connecting the current position to the closest and second closest node of the path,
respectfully and i1 and i2 are the projections of the closest and second closest frames of the path. v2 , meanwhile,
is the vector connecting the closest frame to the second closest frame. The distance from the path, z is calculated
using:
v"
u
u
z = t |v1 |2 − |v2 |
p
(v1 · v2 )2 − |v3 |2 (|v1 |2 − |v2 |2 ) v1 · v3 − |v3 |2
−
2|v3 |2
2|v3 |2
!#2
The symbols here are as they were for s. If you would like to use these equations to calculate s and z then you
should use the GPATH flag. The values of s and z can then be referenced using the gspath and gzpath labels.
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Keyword
Description
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
Generated by Doxygen
5.2 CV Documentation
117
Compulsory keywords
REFERENCE
a pdb file containing the set of reference configurations
TYPE
( default=OPTIMAL-FAST ) the manner in which distances are calculated. More information on
the different metrics that are available in PLUMED can be found in the section of the manual on
Distances from reference configurations
LAMBDA
( default=0 ) the value of the lambda parameter for paths
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
TIMINGS
DISABLE_CHECKS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) disable checks on reference input structures.
NOZPATH
( default=off ) do not calculate the zpath position
NOSPATH
( default=off ) do not calculate the spath position
GPATH
calculate the position on the path using trigonometry The final value can be referenced using label.gpath. You can use multiple instances of this keyword i.e.
GPATH1, GPATH2, GPATH3... The corresponding values are then referenced
using label.gpath-1, label.gpath-2, label.gpath-3...
Examples
In the example below the path is defined using RMSD distance from frames. The reference frames in the path are
defined in the pdb file. In this frame each configuration in the path is separated by a line containing just the word
END.
BEGIN_PLUMED_FILE
p1: PATH REFERENCE=file.pdb TYPE=OPTIMAL LAMBDA=500.0
PRINT ARG=p1.sss,p1.zzz STRIDE=1 FILE=colvar FMT=%8.4f
In the example below the path is defined using the values of two torsional angles (t1 and t2). In addition, the s and
z are calculated using the geometric expressions described above rather than the algebraic expressions that are
used by default.
BEGIN_PLUMED_FILE
t1: TORSION ATOMS=5,7,9,15
t2: TORSION ATOMS=7,9,15,17
pp: PATH TYPE=EUCLIDEAN REFERENCE=epath.pdb GPATH NOSPATH NOZPATH
PRINT ARG=pp.* FILE=colvar
Notice that the LAMBDA parameter is not required here as we are not calculating s and s using the algebraic
formulae defined earlier. The positions of the frames in the path are defined in the file epath.pdb. An extract from
this file looks as shown below.
Generated by Doxygen
118
Collective Variables
REMARK ARG=t1,t2 t1=-4.25053
END
REMARK ARG=t1,t2 t1=-4.11
END
REMARK ARG=t1,t2 t1=-3.96947
END
t2=3.88053
t2=3.75
t2=3.61947
The remarks in this pdb file tell PLUMED the labels that are being used to define the position in the high dimensional
space and the values that these arguments have at each point on the path.
The following input instructs PLUMED to calculate the values of the path collective variables. The frames that
make up this path are defined in the file all.pdb and all distances are measured using the OPTIMAL metric that is
discussed in the manual page on RMSD.
BEGIN_PLUMED_FILE
p2: PATH REFERENCE=all.pdb LAMBDA=69087
PRINT ARG=p2.spath,p2.zpath STRIDE=1 FILE=colvar
If you wish to use collective variable values in the definition of your path you would use an input file with something
like this:
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=1,2
d2: DISTANCE ATOMS=3,4a
p2: PATH REFERENCE=mypath.pdb LAMBDA=2 TYPE=EUCLIDEAN
PRINT ARG=p2.spath,p2.zpath STRIDE=1 FILE=colvar
The corresponding pdb file containing the definitions of the frames in the path would then look like this:
DESCRIPTION: a defintiion of a PATH
REMARK TYPE=EUCLIDEAN
REMARK ARG=d1,d2
REMARK d1=1.0 d2=1.0
END
REMARK TYPE=EUCLIDEAN
REMARK ARG=d1,d2
REMARK d1=2.0 d2=2.0
END
For each frame in the path you must specify the arguments that should be used to calculate the distance between
the instantaneous configuration of the system and the reference configurations together with the values that these
arguments take in each of the reference configurations.
5.2.26
PCAVARS
This is part of the mapping module
Projection on principal component eigenvectors or other high dimensional linear subspace
The collective variables described in Distances from reference configurations allow one to calculate the distance between the instantaneous structure adopted by the system and some high-dimensional, reference configuration. The
problem with doing this is that, as one gets further and further from the reference configuration, the distance from it
becomes a progressively poorer and poorer collective variable. This happens because the ``number" of structures
Generated by Doxygen
5.2 CV Documentation
119
at a distance d from a reference configuration is proportional to dN in an N dimensional space. Consequently, when
d is small the distance from the reference configuration may well be a good collective variable. However, when d is
large it is unlikely that the distance from the reference structure is a good CV. When the distance is large there will
almost certainly be markedly different configuration that have the same CV value and hence barriers in transverse
degrees of freedom.
For these reasons dimensionality reduction is often employed so a projection s of a high-dimensional configuration
X in a lower dimensionality space using a function:
s = F (X − Xref )
where here we have introduced some high-dimensional reference configuration Xref . By far the simplest way to do
this is to use some linear operator for F . That is to say we find a low-dimensional projection by rotating the basis
vectors using some linear algebra:
si =
X
Aik (Xk − Xkref )
k
Here A is a d by D matrix where D is the dimensionality of the high dimensional space and d is the dimensionality
of the lower dimensional subspace. In plumed when this kind of projection you can use the majority of the metrics
detailed on Distances from reference configurations to calculate the displacement, X − Xref , from the reference
configuration. The matrix A can be found by various means including principal component analysis and normal
mode analysis. In both these methods the rows of A would be the principle eigenvectors of a square matrix. For
PCA the covariance while for normal modes the Hessian.
Bug It is not possible to use the DRMSD metric with this variable. You can get around this by listing the set
of distances you wish to calculate for your DRMSD in the plumed file explicitly and using the EUCLIDEAN
metric. MAHALONOBIS and NORM-EUCLIDEAN also do not work with this variable but using these options
makes little sense when projecting on a linear subspace.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
eig
the projections on each eigenvalue are stored on values labeled eig-1, eig-2, ...
residual
the distance of the configuration from the linear
p subspace
P defined by the vectors, ei , that are contained in the rows of A. In other words this is (r 2 − i [r.ei ]2 ) where r is the distance between
the instantaneous position and the reference point.
Compulsory keywords
REFERENCE
a pdb file containing the reference configuration and configurations that define the directions
for each eigenvector
TYPE
( default=OPTIMAL ) The method we are using for alignment to the reference structure
Generated by Doxygen
120
Collective Variables
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
The following input calculates a projection on a linear subspace where the displacements from the reference configuration are calculated using the OPTIMAL metric. Consequently, both translation of the center of mass of the
atoms and rotation of the reference frame are removed from these displacements. The matrix A and the reference
configuration Rref are specified in the pdb input file reference.pdb and the value of all projections (and the residual)
are output to a file called colvar2.
BEGIN_PLUMED_FILE
PCAVARS REFERENCE=reference.pdb TYPE=OPTIMAL LABEL=pca2
PRINT ARG=pca2.* FILE=colvar2
The reference configurations can be specified using a pdb file. The first configuration that you provide is the
reference configuration, which is referred to in the above as X ref subsequent configurations give the directions of
row vectors that are contained in the matrix A above. These directions can be specified by specifying a second
configuration - in this case a vector will be constructed by calculating the displacement of this second configuration
from the reference configuration. A pdb input prepared in this way would look as follows:
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
END
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
END
2 CH3 ACE
5 C
ACE
9 CA ALA
13 HB2 ALA
15 C
ALA
20 HH31 NME
21 HH32 NME
1
1
2
2
2
3
3
12.932
21.312
19.462
21.112
19.422
20.122
18.572
-14.718
-9.928
-11.088
-10.688
7.978
-9.928
-13.148
-6.016
-5.946
-8.986
-12.476
-14.536
-17.746
-16.346
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
2 CH3 ACE
5 C
ACE
9 CA ALA
13 HB2 ALA
15 C
ALA
20 HH31 NME
21 HH32 NME
1
1
2
2
2
3
3
13.932
20.312
18.462
20.112
19.422
20.122
18.572
-14.718
-9.928
-11.088
-11.688
7.978
-9.928
-13.148
-6.016
-5.946
-8.986
-12.476
-12.536
-17.746
-16.346
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
Generated by Doxygen
5.2 CV Documentation
121
Alternatively, the second configuration can specify the components of A explicitly. In this case you need to include
the keyword TYPE=DIRECTION in the remarks to the pdb as shown below.
ATOM
2 CH3 ACE
ATOM
5 C
ACE
ATOM
9 CA ALA
ATOM
13 HB2 ALA
ATOM
15 C
ALA
ATOM
20 HH31 NME
ATOM
21 HH32 NME
END
REMARK TYPE=DIRECTION
ATOM
2 CH3 ACE
ATOM
5 C
ACE
ATOM
9 CA ALA
ATOM
13 HB2 ALA
ATOM
15 C
ALA
ATOM
20 HH31 NME
ATOM
21 HH32 NME
END
1
1
2
2
2
3
3
12.932
21.312
19.462
21.112
19.422
20.122
18.572
1
1
2
2
2
3
3
0.1414
0.0893
0.0207
0.0317
0.1282
0.0053
-0.1019
-14.718
-9.928
-11.088
-10.688
7.978
-9.928
-13.148
-6.016
-5.946
-8.986
-12.476
-14.536
-17.746
-16.346
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
0.3334 -0.0302
-0.1095 -0.1434
-0.321
0.0321
-0.6085 0.0783
-0.4792 0.0797
-0.465
0.0309
-0.4261 -0.0082
1.00
1.00
1.00
1.00
1.00
1.00
1.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
If your metric involves arguments the labels of these arguments in your plumed input file should be specified in the
REMARKS for each of the frames of your path. An input file in this case might look like this:
DESCRIPTION: a pca eigenvector specified using the start point and direction in the HD space.
REMARK WEIGHT=1.0
REMARK ARG=d1,d2
REMARK d1=1.0 d2=1.0
END
REMARK TYPE=DIRECTION
REMARK ARG=d1,d2
REMARK d1=0.1 d2=0.25
END
Here we are working with the EUCLIDEAN metric and notice that we have specified the components of A using D←IRECTION. Consequently, the values of d1 and d2 in the second frame above do not specify a particular coordinate
in the high-dimensional space as in they do in the first frame. Instead these values are the coefficients that can be
used to construct a linear combination of d1 and d2. If we wanted to specify the direction in this metric using the
start and end point of the vector we would write:
DESCRIPTION: a pca eigenvector specified using the start and end point of a vector in the HD space.
REMARK WEIGHT=1.0
REMARK ARG=d1,d2
REMARK d1=1.0 d2=1.0
END
REMARK ARG=d1,d2
REMARK d1=1.1 d2=1.25
END
5.2.27
POSITION
This is part of the colvar module
Calculate the components of the position of an atom.
Notice that single components will not have the proper periodicity! If you need the values to be consistent through
PBC you should use SCALED_COMPONENTS, which defines values that by construction are in the -0.5,0.←5 domain. This is similar to the equivalent flag for DISTANCE. Also notice that by default the minimal image
distance from the origin is considered (can be changed with NOPBC).
Generated by Doxygen
122
Collective Variables
Attention
This variable should be used with extreme care since it allows to easily go into troubles. See comments below.
This variable can be safely used only if Hamiltonian is not invariant for translation (i.e. there are other absolute
positions which are biased, e.g. by position restraints) and cell size and shapes are fixed through the simulation.
If you are not in this situation and still want to use the absolute position of an atom you should first fix the reference
frame. This can be done e.g. using FIT_TO_TEMPLATE.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
x
the x-component of the atom position
y
the y-component of the atom position
z
the z-component of the atom position
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
a
SCALED_COMPONENTS
the normalized projection on the first lattice vector of the atom position
b
SCALED_COMPONENTS
the normalized projection on the second lattice vector of the atom
position
c
SCALED_COMPONENTS
the normalized projection on the third lattice vector of the atom position
The atoms involved can be specified using
ATOM
the atom number. For more information on how to specify lists of atoms see Groups and Virtual Atoms
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) calculate the a, b and c scaled components of the position separately and store them as label.a, label.b and label.c
SCALED_COMPONENTS
Examples
BEGIN_PLUMED_FILE
Generated by Doxygen
5.2 CV Documentation
123
# align to a template
FIT_TO_TEMPLATE REFERENCE=ref.pdb
p: POSITION ATOM=3
PRINT ARG=p.x,p.y,p.z
5.2.28
PROPERTYMAP
This is part of the colvar module
Calculate generic property maps.
This Colvar calculates the property maps according to the work of Spiwok [13].
Basically it calculates
P
i Xi ∗ exp(−λDi (x))
X= P
exp(−λDi (x))
P i
Y
i i ∗ exp(−λDi (x))
Y = P
i exp(−λDi (x))
···
X
1
exp(−λDi (x)))
zzz = − log(
λ
i
where the parameters Xi and Yi are provided in the input pdb (allv.pdb in this case) and Di (x) is the mean squared
displacement after optimal alignment calculated on the pdb frames you input (see Kearsley).
When running with periodic boundary conditions, the atoms should be in the proper periodic image. This is done
automatically since PLUMED 2.5, by considering the ordered list of atoms and rebuilding molecules using a procedure that is equivalent to that done in WHOLEMOLECULES . Notice that rebuilding is local to this action. This is
different from WHOLEMOLECULES which actually modifies the coordinates stored in PLUMED.
In case you want to recover the old behavior you should use the NOPBC flag. In that case you need to take care
that atoms are in the correct periodic image.
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Quantity
Description
zzz
the minimum distance from the reference points
Compulsory keywords
LAMBDA
the lambda parameter is needed for smoothing, is in the units of plumed
REFERENCE
the pdb is needed to provide the various milestones
PROPERTY
the property to be used in the indexing: this goes in the REMARK field of the reference
Generated by Doxygen
124
Collective Variables
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
NEIGH_SIZE
size of the neighbor list
NEIGH_STRIDE
how often the neighbor list needs to be calculated in time units
EPSILON
(default=-1) the maximum distance between the close and the current structure,
the positive value turn on the close structure method
LOG_CLOSE
(default=0) value 1 enables logging regarding the close structure
DEBUG_CLOSE
(default=0) value 1 enables extensive debugging info regarding the close structure, the simulation will run much slower
Examples
BEGIN_PLUMED_FILE
p3: PROPERTYMAP REFERENCE=../../trajectories/path_msd/allv.pdb PROPERTY=X,Y LAMBDA=69087 NEIGH_SIZE=8 NEIGH_ST
PRINT ARG=p3.X,p3.Y,p3.zzz STRIDE=1 FILE=colvar FMT=%8.4f
note that NEIGH_STRIDE=4 NEIGH_SIZE=8 control the neighbor list parameter (optional but recommended for
performance) and states that the neighbor list will be calculated every 4 steps and consider only the closest 8
member to the actual md snapshots.
In this case the input line instructs plumed to look for two properties X and Y with attached values in the REMARK
line of the reference pdb (Note: No spaces from X and = and 1 !!!!). e.g.
REMARK X=1 Y=2
ATOM
1 CL
ATOM
5 CLP
.......
END
REMARK X=2 Y=3
ATOM
1 CL
ATOM
5 CLP
....
END
ALA
ALA
1
1
-3.171
-1.819
0.295
-0.143
2.045
1.679
1.00
1.00
1.00
1.00
ALA
ALA
1
1
-3.175
-1.814
0.365
-0.106
2.024
1.685
1.00
1.00
1.00
1.00
Note
The implementation of this collective variable and of PATHMSD is shared, as well as most input options.
5.2.29
PUCKERING
This is part of the colvar module
Calculate sugar pseudorotation coordinates.
This command can be used to calculate ring's pseudorotations in sugars (puckers). It works for both 5-membered
Generated by Doxygen
5.2 CV Documentation
125
and 6-membered rings. Notice that there are two different implementations depending if one passes 5 or 6 atoms
in the ATOMS keyword.
For 5-membered rings the implementation is the one discussed in [16] . This implementation is simple and can
be used in RNA to distinguish C2'-endo and C3'-endo conformations. Both the polar coordinates (phs and amp)
and the Cartesian coordinates (Zx and Zy) are provided. C2'-endo conformations have negative Zx, whereas
C3'-endo conformations have positive Zy. Notation is consistent with [16] . The five atoms should be provided
as C4',O4',C1',C2',C3'. Notice that this is the same order that can be obtained using the MOLINFO syntax (see
example below).
For 6-membered rings the implementation is the general Cremer-Pople one [17] as also discussed in [18] . This
implementation provides both a triplet with Cartesian components (qx, qy, and qz) and a triplet of polar components
(amplitude, phi, and theta). Applications of this particular implementation are to be published (paper in preparation).
Note
The 6-membered ring implementation distributed with previous versions of PLUMED lead to qx and qy values
that had an opposite sign with respect to those originally defined in [17]. The bug is fixed in version 2.5.
Components of this action are:
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
phs
Pseudorotation phase (5 membered rings)
amp
Pseudorotation amplitude (5 membered rings)
Zx
Pseudorotation x Cartesian component (5 membered rings)
Zy
Pseudorotation y Cartesian component (5 membered rings)
phi
Pseudorotation phase (6 membered rings)
theta
Theta angle (6 membered rings)
amplitude
Pseudorotation amplitude (6 membered rings)
qx
Cartesian component x (6 membered rings)
qy
Cartesian component y (6 membered rings)
qz
Cartesian component z (6 membered rings)
The atoms involved can be specified using
ATOMS
the five or six atoms of the sugar ring in the proper order. For more information on how to specify lists
of atoms see Groups and Virtual Atoms
Options
Generated by Doxygen
126
Collective Variables
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
Examples
This input tells plumed to print the puckering phase angle of the 3rd nucleotide of a RNA molecule on file COLVAR.
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=rna.pdb MOLTYPE=rna
PUCKERING ATOMS=@sugar-3 LABEL=puck
PRINT ARG=puck.phs FILE=COLVAR
5.2.30
TEMPLATE
This is part of the colvar module
This file provides a template for if you want to introduce a new CV.
The atoms involved can be specified using
ATOMS
the keyword with which you specify what atoms to use should be added like this. For more information
on how to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
TEMPLATE_COMPULSORY
all compulsory keywords should be added like this with a description here
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating
distances
( default=off ) flags that are by default not performed should be specified
like this
( default=on ) flags that are by default performed should be specified
like this
TEMPLATE_DEFAULT_OFF_FLAG
TEMPLATE_DEFAULT_ON_FLAG
TEMPLATE_OPTIONAL
all optional keywords that have input should be added like a description
here
Generated by Doxygen
5.2 CV Documentation
127
Examples
BEGIN_PLUMED_FILE
# This should be a sample input.
t: TEMPLATE ATOMS=1,2
PRINT ARG=t STRIDE=100 FILE=COLVAR
(see also PRINT)
5.2.31
TORSION
This is part of the colvar module
Calculate a torsional angle.
This command can be used to compute the torsion between four atoms or alternatively to calculate the angle
between two vectors projected on the plane orthogonal to an axis.
The atoms involved can be specified using
ATOMS
the four atoms involved in the torsional angle
Or alternatively by using
AXIS
two atoms that define an axis. You can use this to find the angle in the plane perpendicular to the
axis between the vectors specified using the VECTOR1 and VECTOR2 keywords.
VECTOR1
VECTOR2
two atoms that define a vector. You can use this in combination with VECTOR2 and AXIS
two atoms that define a vector. You can use this in combination with VECTOR1 and AXIS
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
COSINE
( default=off ) calculate cosine instead of dihedral
Examples
This input tells plumed to print the torsional angle between atoms 1, 2, 3 and 4 on file COLVAR.
Generated by Doxygen
128
Collective Variables
BEGIN_PLUMED_FILE
t: TORSION ATOMS=1,2,3,4
# this is an alternative, equivalent, definition:
# t: TORSION VECTOR1=2,1 AXIS=2,3 VECTOR2=3,4
PRINT ARG=t FILE=COLVAR
If you are working with a protein you can specify the special named torsion angles φ, ψ , ω and χ1 by using TOR←SION in combination with the MOLINFO command. This can be done by using the following syntax.
BEGIN_PLUMED_FILE
MOLINFO MOLTYPE=protein STRUCTURE=myprotein.pdb
t1: TORSION ATOMS=@phi-3
t2: TORSION ATOMS=@psi-4
PRINT ARG=t1,t2 FILE=colvar STRIDE=10
Here, @phi-3 tells plumed that you would like to calculate the φ angle in the third residue of the protein. Similarly
@psi-4 tells plumed that you want to calculate the ψ angle of the fourth residue of the protein.
Both of the previous examples specify that the torsion angle should be calculated based on the position of four
atoms. For the first example in particular the assumption when the torsion is specified in this way is that there are
chemical bonds between atoms 1 and 2, atoms 2 and 3 and atoms 3 and 4. In general, however, a torsional angle
measures the angle between two planes, which have at least one vector in common. As shown below, there is thus
an alternate, more general, way through which we can define a torsional angle:
BEGIN_PLUMED_FILE
t1: TORSION VECTOR1=1,2 AXIS=3,4 VECTOR2=5,6
PRINT ARG=t1 FILE=colvar STRIDE=20
This input instructs PLUMED to calculate the angle between the plane containing the vector connecting atoms 1 and
2 and the vector connecting atoms 3 and 4 and the plane containing this second vector and the vector connecting
atoms 5 and 6. We can even use PLUMED to calculate the torsional angle between two bond vectors around the
z-axis as shown below:
BEGIN_PLUMED_FILE
a0: FIXEDATOM AT=0,0,0
az: FIXEDATOM AT=0,0,1
t1: TORSION VECTOR1=1,2 AXIS=a0,az VECTOR2=5,6
PRINT ARG=t1 FILE=colvar STRIDE=20
5.2.32
VOLUME
This is part of the colvar module
Calculate the volume of the simulation box.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
Generated by Doxygen
5.3 Distances from reference configurations
129
Examples
The following input tells plumed to print the volume of the system
BEGIN_PLUMED_FILE
vol: VOLUME
PRINT ARG=vol
5.3
Distances from reference configurations
One colvar that has been shown to be very successful in studying protein folding is the distance between the
instantaneous configuration and a reference configuration - often the structure of the folded state. When the free
energy of a protein is shown as a function of this collective variable there is a minima for low values of the CV, which
is due to the folded state of the protein. There is then a second minima at higher values of the CV, which is the
minima corresponding to the unfolded state.
A slight problem with this sort of collective variable is that there are many different ways of calculating the distance
from a particular reference structure. The simplest - adding together the distances by which each of the atoms
has been translated in going from the reference configuration to the instantaneous configuration - is not particularly
sensible. A distance calculated in this way does not neglect translation of the center of mass of the molecule and
rotation of the frame of reference. A common practice is thus to remove these components by calculating the RMSD
distance between the reference and instantaneous configurations. This is not the only way to calculate the distance,
however. One could also calculate the total amount by which a large number of collective variables change in
moving from the reference to the instantaneous configurations. One could even combine RMSD distances with the
amount the collective variables change. A full list of the ways distances can be measured in PLUMED is given
below:
DRMSD
Calculate the distance RMSD with respect to a reference structure.
MULTI_RMSD
Calculate the RMSD distance moved by a number of separated domains from their positions
in a reference structure.
Calculate the PCA components ( see [19] and [20] ) for a number of provided eigenvectors
and an average structure. Performs optimal alignment at every step and reports the rmsd so
you know if you are far or close from the average structure.It takes the average structure and
eigenvectors in form of a pdb.Note that beta and occupancy values in the pdb are neglected
and all the weights are placed to 1 (differently from the RMSD colvar for example)
PCARMSD
RMSD
Calculate the RMSD with respect to a reference structure.
TARGET
This function measures the Pythagorean distance from a particular structure measured in the
space defined by some set of collective variables.
These options for calculating distances are re-used in a number of places in the code. For instance they are used
in some of the analysis algorithms that are implemented in PLUMED and in PATH collective variables. Notice that
most of these actions read the reference configuration from a PDB file. Be sure you understand how to format
properly a PDB file to use used in PLUMED (see pdbreader).
5.3.1
DRMSD
This is part of the colvar module
Calculate the distance RMSD with respect to a reference structure.
Generated by Doxygen
130
Collective Variables
To calculate the root-mean-square deviation between the atoms in two configurations you must first superimpose
the two structures in some ways. Obviously, it is the internal vibrational motions of the structure - i.e. not the
translations and rotations - that are interesting. However, aligning two structures by removing the translational and
rotational motions is not easy. Furthermore, in some cases there can be alignment issues caused by so-called
frame-fitting problems. It is thus often cheaper and easier to calculate the distances between all the pairs of atoms.
The distance between the two structures, Xa and Xb can then be measured as:
A
B
d(X , X ) =
s
X
1
[d(xai , xaj ) − d(xbi , xbj )]2
N (N − 1)
i6=j
where N is the number of atoms and d(xi , xj ) represents the distance between atoms i and j . Clearly, this
representation of the configuration is invariant to translation and rotation. However, it can become expensive to
calculate when the number of atoms is large. This can be resolved within the DRMSD colvar by setting LOWER←_CUTOFF and UPPER_CUTOFF. These keywords ensure that only pairs of atoms that are within a certain range
are incorporated into the above sum.
In PDB files the atomic coordinates and box lengths should be in Angstroms unless you are working with natural
units. If you are working with natural units then the coordinates should be in your natural length unit. For more
details on the PDB file format visit http://www.wwpdb.org/docs.html
Compulsory keywords
REFERENCE
a file in pdb format containing the reference structure and the atoms involved in the CV.
LOWER_CUTOFF
only pairs of atoms further than LOWER_CUTOFF are considered in the calculation.
UPPER_CUTOFF
only pairs of atoms closer than UPPER_CUTOFF are considered in the calculation.
TYPE
( default=DRMSD ) what kind of DRMSD would you like to calculate. You can use either
the normal DRMSD involving all the distances between the atoms in your molecule. Alternatively, if you have multiple molecules you can use the type INTER-DRMSD to compute
DRMSD values involving only those distances between the atoms at least two molecules
or the type INTRA-DRMSD to compute DRMSD values involving only those distances
between atoms in the same molecule
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
Examples
The following tells plumed to calculate the distance RMSD between the positions of the atoms in the reference file
and their instantaneous position. Only pairs of atoms whose distance in the reference structure is within 0.1 and 0.8
nm are considered.
BEGIN_PLUMED_FILE
DRMSD REFERENCE=file.pdb LOWER_CUTOFF=0.1 UPPER_CUTOFF=0.8
Generated by Doxygen
5.3 Distances from reference configurations
131
The following tells plumed to calculate a DRMSD value for a pair of molecules.
BEGIN_PLUMED_FILE
DRMSD REFERENCE=file.pdb LOWER_CUTOFF=0.1 UPPER_CUTOFF=0.8 TYPE=INTER-DRMSD
In the input reference file (file.pdb) the atoms in each of the two molecules are separated by a TER command as
shown below.
ATOM
ATOM
ATOM
TER
ATOM
ATOM
END
8
9
10
HT3 ALA
CAY ALA
HY1 ALA
2
2
2
-1.480
-0.096
0.871
-1.560
2.144
2.385
1.212
-0.669
-0.588
1.00
1.00
1.00
1.00
1.00
1.00
DIA
DIA
DIA
H
C
H
12
14
HY3 ALA
OY ALA
2
2
-0.520
-1.139
2.679
0.931
-1.400
-0.973
1.00
1.00
1.00
1.00
DIA
DIA
H
O
In this example the INTER-DRMSD type ensures that the set of distances from which the final quantity is computed
involve one atom from each of the two molecules. If this is replaced by INTRA-DRMSD then only those distances
involving pairs of atoms that are both in the same molecule are computed.
5.3.2
MULTI_RMSD
This is part of the colvar module
Calculate the RMSD distance moved by a number of separated domains from their positions in a reference structure.
When you have large proteins the calculation of the root mean squared deviation between all the atoms in a reference structure and the instantaneous configuration becomes prohibitively expensive. You may thus instead want to
calculate the RMSD between the atoms in a set of domains of your protein and your reference structure. That is to
say:
d(X, Xr ) =
sX
wi |Xi − Xi0 |2
i
where here the sum is over the domains of the protein, Xi represents the positions of the atoms in domain i in the
instantaneous configuration and Xi0 is the positions of the atoms in domain i in the reference configuration. wi is
an optional weight.
The distances for each of the domains in the above sum can be calculated using the DRMSD or RMSD measures
or using a combination of these distance. The reference configuration is specified in a pdb file like the one below:
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
TER
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
END
2
4
6
7
8
9
10
O
HNT
HT1
HT2
HT3
CAY
HY1
ALA
ALA
ALA
ALA
ALA
ALA
ALA
2
2
2
2
2
2
2
-0.926
0.533
-0.216
-0.309
-1.480
-0.096
0.871
-2.447
-0.396
-2.590
-1.255
-1.560
2.144
2.385
-0.497
1.184
1.371
2.315
1.212
-0.669
-0.588
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
DIA
DIA
DIA
DIA
DIA
DIA
DIA
O
H
H
H
H
C
H
12
14
16
18
19
20
21
22
HY3
OY
HN
HA
CB
HB1
HB2
HB3
ALA
ALA
ALA
ALA
ALA
ALA
ALA
ALA
2
2
2
2
2
2
2
2
-0.520
-1.139
1.713
0.099
2.063
2.670
2.556
2.070
2.679
0.931
1.021
-0.774
-1.223
-0.716
-1.051
-2.314
-1.400
-0.973
-0.873
-2.218
-1.276
-2.057
-0.295
-1.490
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
DIA
DIA
DIA
DIA
DIA
DIA
DIA
DIA
H
O
H
H
C
H
H
H
Generated by Doxygen
132
Collective Variables
with the TER keyword being used to separate the various domains in you protein.
Compulsory keywords
REFERENCE
a file in pdb format containing the reference structure and the atoms involved in the CV.
TYPE
( default=MULTI-SIMPLE ) the manner in which RMSD alignment is performed. Should be
MULTI-OPTIMAL, MULTI-OPTIMAL-FAST, MULTI-SIMPLE or MULTI-DRMSD.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) This should be set if you want the mean squared displacement
instead of the root mean squared displacement
SQUARED
Examples
The following tells plumed to calculate the RMSD distance between the positions of the atoms in the reference file
and their instantaneous position. The Kearsley algorithm for each of the domains.
BEGIN_PLUMED_FILE
MULTI_RMSD REFERENCE=file.pdb TYPE=MULTI-OPTIMAL
The following tells plumed to calculate the RMSD distance between the positions of the atoms in the domains
of reference the reference structure and their instantaneous positions. Here distances are calculated using the
DRMSD measure.
BEGIN_PLUMED_FILE
MULTI_RMSD REFERENCE=file.pdb TYPE=MULTI-DRMSD
in this case it is possible to use the following DRMSD options in the pdb file using the REMARK syntax:
NOPBC to calculate distances without PBC
LOWER_CUTOFF=# only pairs of atoms further than LOWER_CUTOFF are considered in the calculation
UPPER_CUTOFF=# only pairs of atoms further than UPPER_CUTOFF are considered in the calculation
as shown in the following example
REMARK NOPBC
REMARK LOWER_CUTOFF=0.1
REMARK UPPER_CUTOFF=0.8
ATOM
2 O
ALA
ATOM
4 HNT ALA
ATOM
6 HT1 ALA
ATOM
7 HT2 ALA
ATOM
8 HT3 ALA
2
2
2
2
2
-0.926
0.533
-0.216
-0.309
-1.480
-2.447
-0.396
-2.590
-1.255
-1.560
-0.497
1.184
1.371
2.315
1.212
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
DIA
DIA
DIA
DIA
DIA
O
H
H
H
H
Generated by Doxygen
5.3 Distances from reference configurations
ATOM
ATOM
TER
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
END
5.3.3
133
9
10
CAY ALA
HY1 ALA
2
2
-0.096
0.871
2.144
2.385
-0.669
-0.588
1.00
1.00
1.00
1.00
DIA
DIA
C
H
12
14
16
18
19
20
21
22
HY3
OY
HN
HA
CB
HB1
HB2
HB3
2
2
2
2
2
2
2
2
-0.520
-1.139
1.713
0.099
2.063
2.670
2.556
2.070
2.679
0.931
1.021
-0.774
-1.223
-0.716
-1.051
-2.314
-1.400
-0.973
-0.873
-2.218
-1.276
-2.057
-0.295
-1.490
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
DIA
DIA
DIA
DIA
DIA
DIA
DIA
DIA
H
O
H
H
C
H
H
H
ALA
ALA
ALA
ALA
ALA
ALA
ALA
ALA
PCARMSD
This is part of the colvar module
Calculate the PCA components ( see [19] and [20] ) for a number of provided eigenvectors and an average structure.
Performs optimal alignment at every step and reports the rmsd so you know if you are far or close from the average
structure. It takes the average structure and eigenvectors in form of a pdb. Note that beta and occupancy values in
the pdb are neglected and all the weights are placed to 1 (differently from the RMSD colvar for example)
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
eig
the projections on each eigenvalue are stored on values labeled eig-1, eig-2, ...
residual
the distance of the present configuration from the configuration supplied as AVERAGE in terms of
mean squared displacement after optimal alignment
Compulsory keywords
AVERAGE
a file in pdb format containing the reference structure and the atoms involved in the CV.
EIGENVECTORS
a file in pdb format containing the reference structure and the atoms involved in the CV.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) This should be set if you want RMSD instead of mean squared
displacement
SQUARED_ROOT
Generated by Doxygen
134
Collective Variables
Examples
BEGIN_PLUMED_FILE
PCARMSD AVERAGE=file.pdb EIGENVECTORS=eigenvectors.pdb
The input is taken so to be compatible with the output you get from g_covar utility of gromacs (suitably adapted to
have a pdb input format).
5.3.4
RMSD
This is part of the colvar module
Calculate the RMSD with respect to a reference structure.
The aim with this colvar it to calculate something like:
d(X, X 0 ) = |X − X 0 |
where X is the instantaneous position of all the atoms in the system and X 0 is the positions of the atoms in
some reference structure provided as input. d(X, X 0 ) thus measures the distance all the atoms have moved
away from this reference configuration. Oftentimes, it is only the internal motions of the structure - i.e. not the
translations of the center of mass or the rotations of the reference frame - that are interesting. Hence, when
calculating the the root-mean-square deviation between the atoms in two configurations you must first superimpose
the two structures in some way. At present PLUMED provides two distinct ways of performing this superposition.
The first method is applied when you use TYPE=SIMPLE in the input line. This instruction tells PLUMED that the
root mean square deviation is to be calculated after the positions of the geometric centers in the reference and
instantaneous configurations are aligned. In other words d(X, x0 ) is to be calculated using:
v
u
X wi
uX x,y,z
P
d(X, X 0 ) = t
(Xi,α − comα (X) − X 0 i,α + comα (X 0 ))2
j wj
α
i
with
comα (X) =
X
i
and
comα (X 0 ) =
X
i
w0
P i 0 Xi,α
j wj
w0
0
P i 0 Xi,α
j wj
Obviously, comα (X) and comα (X 0 ) represent the positions of the center of mass in the reference and instantaneous configurations if the weights $w'$ are set equal to the atomic masses. If the weights are all set equal to
one, however, comα (X) and comα (X 0 ) are the positions of the geometric centers. Notice that there are sets of
weights: w0 and w. The first is used to calculate the position of the center of mass (so it determines how the atoms
are aligned). Meanwhile, the second is used when calculating how far the atoms have actually been displaced.
These weights are assigned in the reference configuration that you provide as input (i.e. the appear in the input file
to this action that you set using REFERENCE=whatever.pdb). This input reference configuration consists of a simple pdb file containing the set of atoms for which you want to calculate the RMSD displacement and their positions
in the reference configuration. It is important to note that the indices in this pdb need to be set correctly. The indices
in this file determine the indices of the instantaneous atomic positions that are used by PLUMED when calculating
this colvar. As such if you want to calculate the RMSD distance moved by the first, fourth, sixth and twenty eighth
Generated by Doxygen
5.3 Distances from reference configurations
135
atoms in the MD codes input file then the indices of the corresponding reference positions in this pdb file should be
set equal to 1, 4, 6 and 28.
The pdb input file should also contain the values of w and w0 . In particular, the OCCUPANCY column (the first
column after the coordinates) is used provides the values of w0 that are used to calculate the position of the center
of mass. The BETA column (the second column after the Cartesian coordinates) is used to provide the w values
which are used in the the calculation of the displacement. Please note that it is possible to use fractional values for
beta and for the occupancy. However, we recommend you only do this when you really know what you are doing
however as the results can be rather strange.
In PDB files the atomic coordinates and box lengths should be in Angstroms unless you are working with natural
units. If you are working with natural units then the coordinates should be in your natural length unit. For more details
on the PDB file format visit http://www.wwpdb.org/docs.html. Make sure your PDB file is correctly
formatted as explained in this page.
A different method is used to calculate the RMSD distance when you use TYPE=OPTIMAL on the input line. In
this case the root mean square deviation is calculated after the positions of geometric centers in the reference and
instantaneous configurations are aligned AND after an optimal alignment of the two frames is performed so that
motion due to rotation of the reference frame between the two structures is removed. The equation for d(X, X 0 ) in
this case reads:
v
uX x,y,z
X wi
X
u
P
[Xi,α − comα (X) −
M (X, X 0 , w0 )α,β (X 0 i,β − comβ (X 0 ))]2
d(X, X 0 ) = t
j wj
α
i
β
where M (X, X 0 , w0 ) is the optimal alignment matrix which is calculated using the Kearsley [21] algorithm. Again
different sets of weights are used for the alignment ( w0 ) and for the displacement calculations ( w). This gives
a great deal of flexibility as it allows you to use a different sets of atoms (which may or may not overlap) for the
alignment and displacement parts of the calculation. This may be very useful when you want to calculate how a
ligand moves about in a protein cavity as you can use the protein as a reference system and do no alignment of the
ligand.
(Note: when this form of RMSD is used to calculate the secondary structure variables (ALPHARMSD,
ANTIBETARMSD and PARABETARMSD all the atoms in the segment are assumed to be part of both the
alignment and displacement sets and all weights are set equal to one)
Please note that there are a number of other methods for calculating the distance between the instantaneous
configuration and a reference configuration that are available in plumed. More information on these various methods
can be found in the section of the manual on Distances from reference configurations.
When running with periodic boundary conditions, the atoms should be in the proper periodic image. This is done
automatically since PLUMED 2.5, by considering the ordered list of atoms and rebuilding molecules using a procedure that is equivalent to that done in WHOLEMOLECULES . Notice that rebuilding is local to this action. This is
different from WHOLEMOLECULES which actually modifies the coordinates stored in PLUMED.
In case you want to recover the old behavior you should use the NOPBC flag. In that case you need to take care
that atoms are in the correct periodic image.
Compulsory keywords
REFERENCE
a file in pdb format containing the reference structure and the atoms involved in the CV.
TYPE
( default=SIMPLE ) the manner in which RMSD alignment is performed. Should be OPTIMAL
or SIMPLE.
Generated by Doxygen
136
Collective Variables
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) This should be set if you want mean squared displacement instead of RMSD
SQUARED
Examples
The following tells plumed to calculate the RMSD distance between the positions of the atoms in the reference file
and their instantaneous position. The Kearsley algorithm is used so this is done optimally.
BEGIN_PLUMED_FILE
RMSD REFERENCE=file.pdb TYPE=OPTIMAL
...
5.3.5
TARGET
This is part of the function module
This function measures the Pythagorean distance from a particular structure measured in the space defined by
some set of collective variables.
This collective variable can be used to calculate something akin to:
d(X, X 0 ) = |X − X 0 |
where X is the instantaneous values for a set of collective variables for the system and X 0 is the values that these
self-same set of collective variables take in some reference structure provided as input. If we call our set of collective
variables {si } then this CV computes:
v
uN
uX
(ref ) 2
d = t (si − si
)
i=1
(ref )
where si
are the values of the CVs in the reference structure and N is the number of input CVs.
We can also calculate normalized euclidean differences using this action and the METRIC=NORM-EUCLIDEAN
flag. In other words, we can compute:
v
uN
uX
(ref ) 2
d=t
σi (si − si
)
i=1
Generated by Doxygen
5.3 Distances from reference configurations
137
where σi is a vector of weights. Lastly, by using the METRIC=MAHALONOBIS we can compute Mahalonobis
distances using:
T
d = s − s(ref ) Σ s − s(ref )
where s is a column vector containing the values of all the CVs and s(ref ) is a column vector containing the values
of the CVs in the reference configuration. Σ is then an N × N matrix that is specified in the input.
Compulsory keywords
TYPE
( default=EUCLIDEAN ) the manner in which the distance should be calculated
REFERENCE
a file in pdb format containing the reference structure. In the PDB file the atomic coordinates
and box lengths should be in Angstroms unless you are working with natural units. If you
are working with natural units then the coordinates should be in your natural length unit. The
charges and masses of the atoms (if required) should be inserted in the beta and occupancy
columns respectively. For more details on the PDB file format visit http://www.wwpdb.←-
org/docs.html
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
Examples
The following input calculates the distance between a reference configuration and the instantaneous position of
the system in the trajectory. The position of the reference configuration is specified by providing the values of the
distance between atoms 1 and 2 and atoms 3 and 4.
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=1,2
d2: DISTANCE ATOMS=3,4
t1: TARGET REFERENCE=reference.pdb TYPE=EUCLIDEAN
PRINT ARG=t1 FILE=colvar
The contents of the file containing the reference structure (reference.pdb) is shown below. As you can see you must
provide information on the labels of the CVs that are being used to define the position of the reference configuration
in this file together with the values that these quantities take in the reference configuration.
DESCRIPTION: a reference point.
REMARK WEIGHT=1.0
REMARK ARG=d1,d2
REMARK d1=1.0 d2=1.0
END
Generated by Doxygen
138
5.4
Collective Variables
Functions
When performing biased dynamics or analyzing a trajectory you may wish to analyze/bias the value of some function
of a set of collective variables rather than the values of the collective variables directly. You can do this with PLUMED
by using any one of the following list of functions.
Notice that in many functions you should explicitly say to PLUMED whether the result is a periodic variable or not
using the keyword PERIODIC. This is crucial to allow a variable to be properly based. To know if a function is
periodic of not you should answer to the following question:
• Can my function change with a discontinuity when I move my atoms in a continuous manner?
In case the answer is no, than you should use PERIODIC=NO. In case the answer is yes, then you should consider
the following question:
• Are the values of the function at the discontinuity always the same or do they change?
In case the answer is that they are the same, you should use PERIODIC=A,B where A is the smallest value and
B is the largest value. In case the answer is that the values at the discontinuity are not always the same, then you
cannot construct a variable that can be biased with PLUMED. Consider the following examples:
BEGIN_PLUMED_FILE
t: TORSION ATOMS=1,2,3,4
# When atoms are moved, t could jump suddenly from -pi to +pi
c: MATHEVAL ARG=t FUNC=x*x*x PERIODIC=-31.0062766802998,31.0062766802998
# When atoms are moved, c could jump suddenly from -pi**3 to +pi**3
# equivalently, we could have used:
# c: COMBINE ARG=t POWERS=3 PERIODIC=-31.0062766802998,31.0062766802998
# compute x/y/z components of the distance between atoms 1 and 10
d: DISTANCE ATOMS=1,10 COMPONENTS
# make a new variable equal to d.z but with the correct periodicity
dz: COMBINE ARG=d.z PERIODIC=-10,10
# here we assumed the system is in a orthorhombic box with z side = 20
COMBINE
Calculate a polynomial combination of a set of other variables.
CUSTOM
Calculate a combination of variables using a custom expression.
ENSEMBLE
Calculates the replica averaging of a collective variable over multiple replicas.
FUNCPATHMSD
This function calculates path collective variables.
FUNCSUMHILLS
This function is intended to be called by the command line tool sum_hills. It is meant to
integrate a HILLS file or an HILLS file interpreted as a histogram in a variety of ways. It
is, therefore, not expected that you use this during your dynamics (it will crash!)
LOCALENSEMBLE
Calculates the average over multiple arguments.
MATHEVAL
PIECEWISE
An alias to the CUSTOM function.
Compute a piece wise straight line through its arguments that passes through a set of
ordered control points.
SORT
This function can be used to sort colvars according to their magnitudes.
STATS
Calculates statistical properties of a set of collective variables with respect to a set of
reference values.
Generated by Doxygen
5.4 Functions
139
In addition to the keywords above, by enabling optional modules you can access to the following keywords:
SELECT
5.4.1
(from PLUMED-ISDB module) Selects an argument based on the value of a SELECTOR.
COMBINE
This is part of the function module
Calculate a polynomial combination of a set of other variables.
The functional form of this function is
Narg
C=
X
ci (xi − ai )pi
i=1
The coefficients c, the parameters a and the powers p are provided as vectors.
Notice that COMBINE is not able to predict which will be periodic domain of the computed value automatically.
The user is thus forced to specify it explicitly. Use PERIODIC=NO if the resulting variable is not periodic, and
PERIODIC=A,B where A and B are the two boundaries if the resulting variable is periodic.
Compulsory keywords
PERIODIC
if the output of your function is periodic then you should specify the periodicity of the function.
If the output is not periodic you must state this using PERIODIC=NO
COEFFICIENTS
( default=1.0 ) the coefficients of the arguments in your function
PARAMETERS
( default=0.0 ) the parameters of the arguments in your function
POWERS
( default=1.0 ) the powers to which you are raising each of the arguments in your function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NORMALIZE
( default=off ) normalize all the coefficients so that in total they are equal to one
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Generated by Doxygen
140
Collective Variables
Examples
The following input tells plumed to print the distance between atoms 3 and 5 its square (as computed from the x,y,z
components) and the distance again as computed from the square root of the square.
BEGIN_PLUMED_FILE
DISTANCE LABEL=dist
ATOMS=3,5 COMPONENTS
COMBINE LABEL=distance2 ARG=dist.x,dist.y,dist.z POWERS=2,2,2 PERIODIC=NO
COMBINE LABEL=distance ARG=distance2 POWERS=0.5 PERIODIC=NO
PRINT ARG=distance,distance2
(See also PRINT and DISTANCE).
The following input tells plumed to add a restraint on the cube of a dihedral angle. Notice that since the angle has a
periodic domain -pi,pi its cube has a domain -pi∗∗3,pi∗∗3.
BEGIN_PLUMED_FILE
t: TORSION ATOMS=1,3,5,7
c: COMBINE ARG=t POWERS=3 PERIODIC=-31.0062766802998,31.0062766802998
RESTRAINT ARG=c KAPPA=10 AT=0
5.4.2
CUSTOM
This is part of the function module
Calculate a combination of variables using a custom expression.
This action computes an arbitrary function of one or more collective variables. Arguments are chosen with the ARG
keyword, and the function is provided with the FUNC string. Notice that this string should contain no space. Within
FUNC, one can refer to the arguments as x,y,z, and t (up to four variables provided as ARG). This names can be
customized using the VAR keyword (see examples below).
This function is implemented using the Lepton library, that allows to evaluate algebraic expressions and to automatically differentiate them.
If you want a function that depends not only on collective variables but also on time you can use the TIME action.
Compulsory keywords
PERIODIC
if the output of your function is periodic then you should specify the periodicity of the function. If
the output is not periodic you must state this using PERIODIC=NO
FUNC
the function you wish to evaluate
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
Generated by Doxygen
5.4 Functions
141
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
VAR
the names to give each of the arguments in the function. If you have up to three
arguments in your function you can use x, y and z to refer to them. Otherwise
you must use this flag to give your variables names.
Examples
The following input tells plumed to perform a metadynamics using as a CV the difference between two distances.
BEGIN_PLUMED_FILE
dAB: DISTANCE ATOMS=10,12
dAC: DISTANCE ATOMS=10,15
diff: CUSTOM ARG=dAB,dAC FUNC=y-x PERIODIC=NO
# notice: the previous line could be replaced with the following
# diff: COMBINE ARG=dAB,dAC COEFFICIENTS=-1,1
METAD ARG=diff WIDTH=0.1 HEIGHT=0.5 BIASFACTOR=10 PACE=100
(see also DISTANCE, COMBINE, and METAD). Notice that forces applied to diff will be correctly propagated to
atoms 10, 12, and 15. Also notice that since CUSTOM is used without the VAR option the two arguments should be
referred to as x and y in the expression FUNC. For simple functions such as this one it is possible to use COMBINE.
The following input tells plumed to print the angle between vectors identified by atoms 1,2 and atoms 2,3 its square
(as computed from the x,y,z components) and the distance again as computed from the square root of the square.
BEGIN_PLUMED_FILE
DISTANCE LABEL=d1 ATOMS=1,2 COMPONENTS
DISTANCE LABEL=d2 ATOMS=2,3 COMPONENTS
CUSTOM ...
LABEL=theta
ARG=d1.x,d1.y,d1.z,d2.x,d2.y,d2.z
VAR=ax,ay,az,bx,by,bz
FUNC=acos((ax*bx+ay*by+az*bz)/sqrt((ax*ax+ay*ay+az*az)*(bx*bx+by*by+bz*bz))
PERIODIC=NO
... CUSTOM
PRINT ARG=theta
(See also PRINT and DISTANCE).
Notice that this action implements a large number of functions (trigonometric, exp, log, etc). Among the useful
functions, have a look at the step function (that is the Heaviside function). step(x) is defined as 1 when x is
positive and 0 when x is negative. This allows for a straightforward implementation of if clauses.
For example, imagine that you want to implement a restraint that only acts when a distance is larger than 0.5. You
can do it with
Generated by Doxygen
142
Collective Variables
BEGIN_PLUMED_FILE
d: DISTANCE ATOMS=10,15
m: CUSTOM ARG=d FUNC=0.5*step(0.5-x)+x*step(x-0.5) PERIODIC=NO
# check the function you are applying:
PRINT ARG=d,n FILE=checkme
RESTRAINT ARG=d AT=0.5 KAPPA=10.0
(see also DISTANCE, PRINT, and RESTRAINT)
The meaning of the function 0.5∗step(0.5-x)+x∗step(x-0.5) is:
• If x<0.5 (step(0.5-x)!=0) use 0.5
• If x>0.5 (step(x-0.5)!=0) use x Notice that the same could have been obtained using an UPPER_WALLS
However, with CUSTOM you can create way more complex definitions.
Warning
If you apply forces on the variable (as in the previous example) you should make sure that the variable is
continuous! Conversely, if you are just analyzing a trajectory you can safely use discontinuous variables.
A possible continuity check with gnuplot is
# this allow to step function to be used in gnuplot:
gnuplot> step(x)=0.5*(erf(x*10000000)+1)
# here you can test your function
gnuplot> p 0.5*step(0.5-x)+x*step(x-0.5)
Also notice that you can easily make logical operations on the conditions that you create. The equivalent of the
AND operator is the product: step(1.0-x)∗step(x-0.5) is only equal to 1 when x is between 0.5 and 1.0.
By combining negation and AND you can obtain an OR. That is, 1-step(1.0-x)∗step(x-0.5) is only equal
to 1 when x is outside the 0.5-1.0 interval.
CUSTOM can be used in combination with DISTANCE to implement variants of the DISTANCE keyword that were
present in PLUMED 1.3 and that allowed to compute the distance of a point from a line defined by two other points,
or the progression along that line.
BEGIN_PLUMED_FILE
# take center of atoms 1 to 10 as reference point 1
p1: CENTER ATOMS=1-10
# take center of atoms 11 to 20 as reference point 2
p2: CENTER ATOMS=11-20
# take center of atoms 21 to 30 as reference point 3
p3: CENTER ATOMS=21-30
# compute distances
d12: DISTANCE ATOMS=p1,p2
d13: DISTANCE ATOMS=p1,p3
d23: DISTANCE ATOMS=p2,p3
# compute progress variable of the projection of point p3
# along the vector joining p1 and p2
# notice that progress is measured from the middle point
onaxis: CUSTOM ARG=d13,d23,d12 FUNC=(0.5*(y^2-x^2)/z) PERIODIC=NO
# compute between point p3 and the vector joining p1 and p2
fromaxis: CUSTOM ARG=d13,d23,d12,onaxis VAR=x,y,z,o FUNC=(0.5*(y^2+x^2)-o^2-0.25*z^2) PERIODIC=NO
PRINT ARG=onaxis,fromaxis
Notice that these equations have been used to combine RMSD from different snapshots of a protein so as to define
progression (S) and distance (Z) variables [22].
5.4.2.1
TIME
Generated by Doxygen
5.4 Functions
143
This is part of the generic module
retrieve the time of the simulation to be used elsewhere
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
Examples
BEGIN_PLUMED_FILE
TIME
LABEL=t1
PRINT ARG=t1
5.4.3
ENSEMBLE
This is part of the function module
Calculates the replica averaging of a collective variable over multiple replicas.
Each collective variable is averaged separately and stored in a component labelled label.cvlabel.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
REWEIGHT
( default=off ) simple REWEIGHT using the latest ARG as energy
CENTRAL
( default=off ) calculate a central moment instead of a standard moment
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
TEMP
the system temperature - this is only needed if you are reweighting
MOMENT
the moment you want to calculate in alternative to the mean or the variance
POWER
the power of the mean (and moment)
Generated by Doxygen
144
Collective Variables
Examples
The following input tells plumed to calculate the distance between atoms 3 and 5 and the average it over the
available replicas.
BEGIN_PLUMED_FILE
dist: DISTANCE ATOMS=3,5
ens: ENSEMBLE ARG=dist
PRINT ARG=dist,ens.dist
5.4.4
FUNCPATHMSD
This is part of the function module
This function calculates path collective variables.
This is the Path Collective Variables implementation ( see [5] ). This variable computes the progress along a given
set of frames that is provided in input ("s" component) and the distance from them ("z" component). It is a function
of mean squared displacement that are obtained by the joint use of mean squared displacement variables with the
SQUARED flag (see below).
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
s
the position on the path
z
the distance from the path
Compulsory keywords
LAMBDA
the lambda parameter is needed for smoothing, is in the units of plumed
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
Generated by Doxygen
5.4 Functions
145
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
NEIGH_SIZE
size of the neighbor list
NEIGH_STRIDE
how often the neighbor list needs to be calculated in time units
Examples
Here below is a case where you have defined three frames and you want to calculate the progress along the path
and the distance from it in p1
BEGIN_PLUMED_FILE
t1: RMSD REFERENCE=frame_1.dat TYPE=OPTIMAL SQUARED
t2: RMSD REFERENCE=frame_21.dat TYPE=OPTIMAL SQUARED
t3: RMSD REFERENCE=frame_42.dat TYPE=OPTIMAL SQUARED
p1: FUNCPATHMSD ARG=t1,t2,t3 LAMBDA=500.0
PRINT ARG=t1,t2,t3,p1.s,p1.z STRIDE=1 FILE=colvar FMT=%8.4f
In this second example is shown how to define a PATH in the CONTACTMAP space:
BEGIN_PLUMED_FILE
CONTACTMAP ...
ATOMS1=1,2 REFERENCE1=0.1
ATOMS2=3,4 REFERENCE2=0.5
ATOMS3=4,5 REFERENCE3=0.25
ATOMS4=5,6 REFERENCE4=0.0
SWITCH={RATIONAL R_0=1.5}
LABEL=c1
CMDIST
... CONTACTMAP
CONTACTMAP ...
ATOMS1=1,2 REFERENCE1=0.3
ATOMS2=3,4 REFERENCE2=0.9
ATOMS3=4,5 REFERENCE3=0.45
ATOMS4=5,6 REFERENCE4=0.1
SWITCH={RATIONAL R_0=1.5}
LABEL=c2
CMDIST
... CONTACTMAP
CONTACTMAP ...
ATOMS1=1,2 REFERENCE1=1.0
ATOMS2=3,4 REFERENCE2=1.0
ATOMS3=4,5 REFERENCE3=1.0
ATOMS4=5,6 REFERENCE4=1.0
SWITCH={RATIONAL R_0=1.5}
LABEL=c3
Generated by Doxygen
146
Collective Variables
CMDIST
... CONTACTMAP
p1: FUNCPATHMSD ARG=c1,c2,c3 LAMBDA=500.0
PRINT ARG=c1,c2,c3,p1.s,p1.z STRIDE=1 FILE=colvar FMT=%8.4f
In this third example is shown how to define a PATH in the PIV space:
BEGIN_PLUMED_FILE
PIV ...
LABEL=c1
PRECISION=1000
NLIST
REF_FILE=Ref1.pdb
PIVATOMS=2
ATOMTYPES=A,B
ONLYDIRECT
SFACTOR=1.0,0.2
SORT=1,1
SWITCH1={RATIONAL
SWITCH2={RATIONAL
NL_CUTOFF=1.2,1.2
NL_STRIDE=10,10
NL_SKIN=0.1,0.1
... PIV
PIV ...
LABEL=c2
PRECISION=1000
NLIST
REF_FILE=Ref2.pdb
PIVATOMS=2
ATOMTYPES=A,B
ONLYDIRECT
SFACTOR=1.0,0.2
SORT=1,1
SWITCH1={RATIONAL
SWITCH2={RATIONAL
NL_CUTOFF=1.2,1.2
NL_STRIDE=10,10
NL_SKIN=0.1,0.1
... PIV
R_0=0.6 MM=12 NN=4}
R_0=0.5 MM=10 NN=5}
R_0=0.6 MM=12 NN=4}
R_0=0.4 MM=10 NN=5}
p1: FUNCPATHMSD ARG=c1,c2 LAMBDA=0.180338
METAD ARG=p1.s,p1.z SIGMA=0.01,0.2 HEIGHT=0.8 PACE=500
LABEL=res
PRINT ARG=c1,c2,p1.s,p1.z,res.bias STRIDE=500 FILE=colvar FMT=%15.6f
5.4.5
FUNCSUMHILLS
This is part of the function module
This function is intended to be called by the command line tool sum_hills. It is meant to integrate a HILLS file or an
HILLS file interpreted as a histogram in a variety of ways. It is, therefore, not expected that you use this during your
dynamics (it will crash!)
In the future one could implement periodic integration during the metadynamics or straightforward MD as a tool to
check convergence
Options
Generated by Doxygen
5.4 Functions
147
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ISCLTOOL
( default=on ) use via plumed command line: calculate at read phase and then
go
PARALLELREAD
( default=off ) read parallel HILLS file
NEGBIAS
( default=off ) dump negative bias ( -bias ) instead of the free energy: needed
in well tempered with flexible hills
NOHISTORY
( default=off ) to be used with INITSTRIDE: it splits the bias/histogram in pieces
without previous history
MINTOZERO
( default=off ) translate the resulting bias/histogram to have the minimum to
zero
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
HILLSFILES
source file for hills creation(may be the same as HILLS)
HISTOFILES
source file for histogram creation(may be the same as HILLS)
HISTOSIGMA
sigmas for binning when the histogram correction is needed
PROJ
only with sumhills: the projection on the CVs
KT
only with sumhills: the kt factor when projection on CVs
GRID_MIN
the lower bounds for the grid
GRID_MAX
the upper bounds for the grid
GRID_BIN
the number of bins for the grid
GRID_SPACING
the approximate grid spacing (to be used as an alternative or together with
GRID_BIN)
INTERVAL
OUTHILLS
set one dimensional INTERVAL
output file for hills
OUTHISTO
output file for histogram
INITSTRIDE
stride if you want an initial dump
STRIDE
stride when you do it on the fly
FMT
the format that should be used to output real numbers
Examples
There are currently no examples for this keyword.
5.4.6
LOCALENSEMBLE
Generated by Doxygen
148
Collective Variables
This is part of the function module
Calculates the average over multiple arguments.
If more than one collective variable is given for each argument then they are averaged separately. The average is
stored in a component labelled label.cvlabel.
Compulsory keywords
NUM
the number of local replicas
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
The following input tells plumed to calculate the chemical shifts for four different proteins in the same simulation box
then average them, calculated the sum of the squared deviation with respect to the experimental values and applies
a linear restraint.
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=data/template.pdb
chaina:
chainb:
chainc:
chaind:
GROUP
GROUP
GROUP
GROUP
ATOMS=1-1640
ATOMS=1641-3280
ATOMS=3281-4920
ATOMS=4921-6560
WHOLEMOLECULES ENTITY0=chaina ENTITY1=chainb ENTITY2=chainc ENTITY3=chaind
csa: CS2BACKBONE ATOMS=chaina NRES=100 DATA=data/ TEMPLATE=chaina.pdb NOPBC
csb: CS2BACKBONE ATOMS=chainb NRES=100 DATA=data/ TEMPLATE=chainb.pdb NOPBC
csc: CS2BACKBONE ATOMS=chainc NRES=100 DATA=data/ TEMPLATE=chainc.pdb NOPBC
Generated by Doxygen
5.4 Functions
149
csd: CS2BACKBONE ATOMS=chaind NRES=100 DATA=data/ TEMPLATE=chaind.pdb NOPBC
ensca:
enscb:
ensco:
enshn:
ensnh:
stca:
stcb:
stco:
sthn:
stnh:
LOCALENSEMBLE
LOCALENSEMBLE
LOCALENSEMBLE
LOCALENSEMBLE
LOCALENSEMBLE
STATS
STATS
STATS
STATS
STATS
NUM=4
NUM=4
NUM=4
NUM=4
NUM=4
ARG1=(csa\.ca_.*)
ARG1=(csa\.cb_.*)
ARG1=(csa\.co_.*)
ARG1=(csa\.hn_.*)
ARG1=(csa\.nh_.*)
ARG=(ensca\.csa\.ca_.*)
ARG=(enscb\.csa\.cb_.*)
ARG=(ensco\.csa\.co_.*)
ARG=(enshn\.csa\.hn_.*)
ARG=(ensnh\.csa\.nh_.*)
ARG2=(csb\.ca_.*)
ARG2=(csb\.cb_.*)
ARG2=(csb\.co_.*)
ARG2=(csb\.hn_.*)
ARG2=(csb\.nh_.*)
PARARG=(csa\.expca_.*)
PARARG=(csa\.expcb_.*)
PARARG=(csa\.expco_.*)
PARARG=(csa\.exphn_.*)
PARARG=(csa\.expnh_.*)
ARG3=(csc\.ca_.*)
ARG3=(csc\.cb_.*)
ARG3=(csc\.co_.*)
ARG3=(csc\.hn_.*)
ARG3=(csc\.nh_.*)
ARG4=(csd\.ca_.*)
ARG4=(csd\.cb_.*)
ARG4=(csd\.co_.*)
ARG4=(csd\.hn_.*)
ARG4=(csd\.nh_.*)
SQDEVSUM
SQDEVSUM
SQDEVSUM
SQDEVSUM
SQDEVSUM
res: RESTRAINT ARG=stca.*,stcb.*,stco.*,sthn.*,stnh.* AT=0.,0.,0.,0.,0. KAPPA=0.,0.,0.,0.,0 SLOPE=16.,16.,12.,
5.4.7
MATHEVAL
This is part of the function module
An alias to the CUSTOM function.
This alias is kept in order to maintain compatibility with previous PLUMED versions. However, notice that as of
PLUMED 2.5 the libmatheval library is not linked anymore, and the MATHEVAL function is implemented using the
Lepton library.
Compulsory keywords
PERIODIC
if the output of your function is periodic then you should specify the periodicity of the function. If
the output is not periodic you must state this using PERIODIC=NO
FUNC
the function you wish to evaluate
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Generated by Doxygen
150
Collective Variables
VAR
the names to give each of the arguments in the function. If you have up to three
arguments in your function you can use x, y and z to refer to them. Otherwise
you must use this flag to give your variables names.
Examples
Just replace CUSTOM with MATHEVAL.
BEGIN_PLUMED_FILE
d: DISTANCE ATOMS=10,15
m: MATHEVAL ARG=d FUNC=0.5*step(0.5-x)+x*step(x-0.5) PERIODIC=NO
# check the function you are applying:
PRINT ARG=d,n FILE=checkme
RESTRAINT ARG=d AT=0.5 KAPPA=10.0
(see also DISTANCE, PRINT, and RESTRAINT)
5.4.8
PIECEWISE
This is part of the function module
Compute a piece wise straight line through its arguments that passes through a set of ordered control points.
For variables less than the first (greater than the last) point, the value of the first (last) point is used.
yi+1 − yi
(s − xi ) + yi ; if xi < s < xi+1
xi+1 − xi
yN ; if x > xN −1
y1 ; if x < x0
Control points are passed using the POINT0=... POINT1=... syntax as in the example below
If one argument is supplied, it results in a scalar quantity. If multiple arguments are supplied, it results in a vector of
values. Each value will be named as the name of the original argument with suffix _pfunc.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
_pfunc
one or multiple instances of this quantity can be referenced elsewhere in the input file. These
quantities will be named with the arguments of the function followed by the character string _pfunc.
These quantities tell the user the values of the piece wise functions of each of the arguments.
Generated by Doxygen
5.4 Functions
151
Compulsory keywords
POINT
This keyword is used to specify the various points in the function above. You can use multiple instances
of this keyword i.e. POINT1, POINT2, POINT3...
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
BEGIN_PLUMED_FILE
dist1: DISTANCE ATOMS=1,10
dist2: DISTANCE ATOMS=2,11
pw: PIECEWISE POINT0=1,10 POINT1=1,PI POINT2=3,10 ARG=dist1
ppww: PIECEWISE POINT0=1,10 POINT1=1,PI POINT2=3,10 ARG=dist1,dist2
PRINT ARG=pw,ppww.dist1_pfunc,ppww.dist2_pfunc
5.4.9
SORT
This is part of the function module
This function can be used to sort colvars according to their magnitudes.
Description of components
This function sorts its arguments according to their magnitudes. The lowest argument will be labelled label.1, the
second lowest will be labelled label.2 and so on.
Generated by Doxygen
152
Collective Variables
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
The following input tells plumed to print the distance of the closest and of the farthest atoms to atom 1, chosen
among atoms from 2 to 5
BEGIN_PLUMED_FILE
d12: DISTANCE ATOMS=1,2
d13: DISTANCE ATOMS=1,3
d14: DISTANCE ATOMS=1,4
d15: DISTANCE ATOMS=1,5
sort: SORT ARG=d12,d13,d14,d15
PRINT ARG=sort.1,sort.4
5.4.10
STATS
This is part of the function module
Calculates statistical properties of a set of collective variables with respect to a set of reference values.
In particular it calculates and stores as components the sum of the squared deviations, the correlation, the slope
and the intercept of a linear fit.
The reference values can be either provided as values using PARAMETERS or using value without derivatives
from other actions using PARARG (for example using experimental values from collective variables such as
CS2BACKBONE, RDC, NOE, PRE).
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Generated by Doxygen
5.4 Functions
153
Quantity
Description
sqdevsum
the sum of the squared deviations between arguments and parameters
corr
the correlation between arguments and parameters
slope
the slope of a linear fit between arguments and parameters
intercept
the intercept of a linear fit between arguments and parameters
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
sqd
SQDEV
the squared deviations between arguments and parameters
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
SQDEVSUM
( default=off ) calculates only SQDEVSUM
SQDEV
( default=off ) calculates and store the SQDEV as components
UPPERDISTS
( default=off ) calculates and store the SQDEV as components
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
PARARG
the input for this action is the scalar output from one or more other actions
without derivatives.
the parameters of the arguments in your function
PARAMETERS
Examples
The following input tells plumed to print the distance between three couple of atoms and compare them with three
reference distances.
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=10,50
d2: DISTANCE ATOMS=1,100
d3: DISTANCE ATOMS=45,75
st: STATS ARG=d1,d2,d3 PARAMETERS=1.5,4.0,2.0
PRINT ARG=d1,d2,d3,st.*
Generated by Doxygen
154
5.5
Collective Variables
MultiColvar
Oftentimes, when you do not need one of the collective variables described elsewhere in the manual, what you want
instead is a function of a distribution of collective variables of a particular type. In other words, you would like to
calculate a function something like this:
X
s=
g[f ({X}i )]
i
In this expression g is a function that takes in one argument and f is a function that takes a set of atomic positions
as argument. The symbol {X}i is used to indicate the fact that the function f is evaluated for a number of different
sets of atoms. If you would just like to output the values of all the various f functions you should use the command
DUMPMULTICOLVAR
This functionality is useful if you need to calculate a minimum distance or the number of coordination numbers
greater than a 3.0.
To avoid duplicating the code to calculate an angle or distance many times and to make it easier to implement
very complex collective variables PLUMED provides these sort of collective variables using so-called MultiColvars.
MultiColvars are named in this way because a single PLUMED action can be used to calculate a number of different
collective variables. For instance the DISTANCES action can be used to calculate the minimum distance, the
number of distances less than a certain value, the number of distances within a certain range... A more detailed
introduction to multicolvars is provided in this 10-minute video. Descriptions of the various multicolvars that
are implemented in PLUMED 2 are given below:
ANGLES
Calculate functions of the distribution of angles .
BOND_DIRECTIONS
Calculate the vectors connecting atoms that are within cutoff defined using a
switching function.
BRIDGE
Calculate the number of atoms that bridge two parts of a structure
COORDINATIONNUMBER
Calculate the coordination numbers of atoms so that you can then calculate functions of the distribution of coordination numbers such as the minimum, the number
less than a certain quantity and so on.
DENSITY
Calculate functions of the density of atoms as a function of the box. This allows
one to calculate the number of atoms in half the box.
Calculate the distances between one or many pairs of atoms. You can then calculate functions of the distribution of distances such as the minimum, the number
less than a certain quantity and so on.
DISTANCES
FCCUBIC
HBPAMM_SH
INPLANEDISTANCES
MOLECULES
PLANES
Measure how similar the environment around atoms is to that found in a FCC
structure.
Number of HBPAMM hydrogen bonds formed by each hydrogen atom in the system
Calculate distances in the plane perpendicular to an axis
Calculate the vectors connecting a pair of atoms in order to represent the orientation of a molecule.
Calculate the plane perpendicular to two vectors in order to represent the orientation of a planar molecule.
Q3
Calculate 3rd order Steinhardt parameters.
Q4
Calculate fourth order Steinhardt parameters.
Q6
Calculate sixth order Steinhardt parameters.
SIMPLECUBIC
Calculate whether or not the coordination spheres of atoms are arranged as they
would be in a simple cubic structure.
TETRAHEDRAL
Calculate the degree to which the environment about ions has a tetrahedral order.
TORSIONS
Calculate whether or not a set of torsional angles are within a particular range.
XANGLES
Calculate the angles between the vector connecting two atoms and the x axis.
XDISTANCES
Calculate the x components of the vectors connecting one or many pairs of
atoms.You can then calculate functions of the distribution of values such as the
minimum, the number less than a certain quantity and so on.
Generated by Doxygen
5.5 MultiColvar
155
XYDISTANCES
Calculate distance between a pair of atoms neglecting the z-component.
XYTORSIONS
Calculate the torsional angle around the x axis from the positive y direction.
XZDISTANCES
Calculate distance between a pair of atoms neglecting the y-component.
XZTORSIONS
Calculate the torsional angle around the x axis from the positive z direction.
YANGLES
Calculate the angles between the vector connecting two atoms and the y axis.
YDISTANCES
Calculate the y components of the vectors connecting one or many pairs of
atoms.You can then calculate functions of the distribution of values such as the
minimum, the number less than a certain quantity and so on.
YXTORSIONS
Calculate the torsional angle around the y axis from the positive x direction.
YZDISTANCES
Calculate distance between a pair of atoms neglecting the x-component.
YZTORSIONS
Calculate the torsional angle around the y axis from the positive z direction.
ZANGLES
Calculate the angles between the vector connecting two atoms and the z axis.
ZDISTANCES
Calculate the z components of the vectors connecting one or many pairs of
atoms.You can then calculate functions of the distribution of values such as the
minimum, the number less than a certain quantity and so on.
ZXTORSIONS
Calculate the torsional angle around the z axis from the positive x direction.
ZYTORSIONS
Calculate the torsional angle around the z axis from the positive y direction.
To instruct PLUMED to calculate a multicolvar you give an instruction that looks something like this:
NAME TOL=0.001 LABEL=label
Oftentimes the simplest way to specify the atoms involved is to use multiple instances of the ATOMS keyword i.e.
ATOMS1, ATOMS2, ATOMS3,... Separate instances of the quantity specified by NAME are then calculated for
each of the sets of atoms. For example if the command issued contains the following:
BEGIN_PLUMED_FILE
DISTANCES ATOMS1=1,2 ATOMS2=3,4 ATOMS3=5,6
The distances between atoms 1 and 2, atoms 3 and 4, and atoms 5 and 6 are calculated. Obviously, generating this
sort of input is rather tedious so short cuts are also available many of the collective variables. These are described
on the manual pages for the actions.
After specifying the atoms involved you sometimes need to specify some parameters that required in the calculation.
For instance, for COORDINATIONNUMBER - the number of atoms in the first coordination sphere of each of the
atoms in the system - you need to specify the parameters for a switchingfunction that will tell us whether or not an
atom is in the first coordination sphere. Details as to how to do this are provided on the manual pages.
One of the most important keywords for multicolvars is the TOL keyword. This specifies that terms in sums that
contribute less than a certain value can be ignored. In addition, it is assumed that the derivative with respect to
these terms are essentially zero. By increasing the TOL parameter you can increase the speed of the calculation.
Be aware, however, that this increase in speed is only possible because you are lowering the accuracy with which
you are computing the quantity of interest.
Once you have specified the base quantities that are to be calculated from the atoms involved and any parameters
you need to specify what function of these base quantities is to be calculated. For most multicolvars you can
calculate the minimum, the number less than a target value, the number within a certain range, the number more
than a target value and the average value directly.
5.5.1
MultiColvar functions
It is possible to use multicolvars to calculate complicated collective variables by exploiting the fact that the output
from one multicolvar can be used as input to a second multicolvar. One simple way of exploiting this functionality is
to filter the atoms based on the value they have for a symmetry function. For example you might want to consider
only those atoms that with a COORDINATIONNUMBER higher that a certain threshold when calculating some
particularly expensive symmetry function such as Q6. The following methods can thus all be used to filter the
values of multicolvars in this way:
Generated by Doxygen
156
Collective Variables
MFILTER_BETWEEN
This action can be used to filter the colvar values calculated by a mcolvso that one can
compute the mean and so on for only those multicolvars within a certain range.
MFILTER_LESS
This action can be used to filter the distribution of colvar values in a mcolvso that one
can compute the mean and so on for only those multicolvars less than a tolerance.
MFILTER_MORE
This action can be used to filter the distribution of colvar values in a mcolvso that one
can compute the mean and so on for only those multicolvars more than a tolerance.
An alternative way of filtering atoms is to consider only those atoms in a particular part of the simulation box. This
can be done by exploiting the following methods
AROUND
This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a particular, user-specified part of of the cell.
CAVITY
This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a box defined by the positions of four atoms.
INCYLINDER
This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a particular, user-specified part of of the cell.
INENVELOPE
This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a region where the density of a certain type of atom is
high.
INSPHERE
This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a particular, user-specified part of of the cell.
TETRAHEDRALPORE
This quantity can be used to calculate functions of the distribution of collective variables for the atoms lie that lie in a box defined by the positions of four atoms at the
corners of a tetrahedron.
The idea with these methods is that function of the form:
s=
X
w({X}i )g[f ({X}i )]
i
can be evaluated where once again g is a function with one argument and g is a function of a set of atomic positions.
The difference from the more general function described earlier is that we now have a weight w which is again a
function of the atomic positions. This weight varies between zero and one and it is this weight that is calculated in
the list of filtering methods and volume methods described in the lists above.
In addition to these volume and filtering methods it is also possible to calculate the local average of a quantities in
the manner described in [23] using the LOCAL_AVERAGE method. Furthermore, in many cases Q6, MOLECULES
and PLANES the symmetry function being evaluated is a vector. You can thus construct a variety of novel collective
variables by taking dot products of vectors on adjacent atoms as described below:
GRADIENT
Calculate the gradient of the average value of a multicolvar value
INTERMOLECULARTORSIONS
Calculate torsion angles between vectors on adjacent molecules
LOCAL_AVERAGE
Calculate averages over spherical regions centered on atoms
LOCAL_Q3
Calculate the local degree of order around an atoms by taking the average
dot product between the q3 vector on the central atom and the q3 vector on
the atoms in the first coordination sphere.
LOCAL_Q4
Calculate the local degree of order around an atoms by taking the average
dot product between the q4 vector on the central atom and the q4 vector on
the atoms in the first coordination sphere.
LOCAL_Q6
Calculate the local degree of order around an atoms by taking the average
dot product between the q6 vector on the central atom and the q6 vector on
the atoms in the first coordination sphere.
MCOLV_COMBINE
Calculate linear combinations of multiple multicolvars
MCOLV_PRODUCT
Calculate a product of multiple multicolvars
Generated by Doxygen
5.5 MultiColvar
157
NLINKS
Calculate number of pairs of atoms/molecules that are "linked"
PAMM
Probabilistic analysis of molecular motifs.
POLYMER_ANGLES
Calculate a function to investigate the relative orientations of polymer angles
SMAC
Calculate a variant on the SMAC collective variable discussed in [24]
The final set of functions that you can apply on multicolvars are functions that transform all the colvars calculated
using a multicolvar using a function. This can be useful if you are calculating some complicated derived quantity of
some simpler quantity. It is also useful if you are calculating a Willard Chandler surface or a histogram. The actions
that you can use to perform these transforms are:
MTRANSFORM_BETWEEN
This action can be used to transform the colvar values calculated by a Multi←Colvar using a histogrambead
MTRANSFORM_LESS
This action can be used to transform the colvar values calculated by a
MultiColvar using a switchingfunction
MTRANSFORM_MORE
This action can be used to transform the colvar values calculated by a
MultiColvar using one minus a switchingfunction
5.5.2
MultiColvar bias
There may be occasions when you want add restraints on many collective variables. For instance if you are studying
a cluster you might want to add a wall on the distances between each of the atoms and the center of mass of the
cluster in order to prevent the cluster subliming. Alternatively, you may wish to insist that a particular set of atoms in
your system all have a coordination number greater than 2. You can add these sorts of restraints by employing the
following biases, which all act on the set of collective variable values calculated by a multicolvar. So for example the
following set of commands:
BEGIN_PLUMED_FILE
COM ATOMS=1-20 LABEL=c1
DISTANCES GROUPA=c1 GROUPB=1-20 LABEL=d1
UWALLS DATA=d1 AT=2.5 KAPPA=0.2 LABEL=sr
creates the aforementioned set of restraints on the distances between the 20 atoms in a cluster and the center of
mass of the cluster.
The list of biases of this type are as follows:
LWALLS
UWALLS
Add LOWER_WALLS restraints on all the multicolvar values
Add UPPER_WALLS restraints on all the multicolvar values
Notice that (in theory) you could also use this functionality to add additional terms to your force field or to implement
your force field.
5.5.3
Extracting all the base quantities
There may be occasions where you want to get information on all the individual colvar values that you have
calculated. For example you might want to output the values of all the coordination numbers calculated by a
COORDINATIONNUMBER action. You can thus use the following command to extract this sort of information,
DUMPMULTICOLVAR.
5.5.4
ANGLES
Generated by Doxygen
158
Collective Variables
This is part of the multicolvar module
Calculate functions of the distribution of angles .
You can use this command to calculate functions such as:
f (x) =
X
g(θijk )
ijk
Alternatively you can use this command to calculate functions such as:
f (x) =
X
s(rij )s(rjk )g(θijk )
ijk
where s(r) is a switchingfunction. This second form means that you can use this to calculate functions of the angles
in the first coordination sphere of an atom / molecule [25].
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
Generated by Doxygen
5.5 MultiColvar
ATOMS
159
the atoms involved in each of the angles you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one angle will be calculated for each ATOM keyword you specify
(all ATOM keywords should provide the indices of three atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate angles for each distinct set of three atoms in the group
Or alternatively by using
GROUPA
A group of central atoms about which angles should be calculated
GROUPB
When used in conjunction with GROUPA this keyword instructs plumed to calculate all distinct
angles involving one atom from GROUPA and two atoms from GROUPB. The atom from GROUPA
is the central atom.
Or alternatively by using
GROUPC
This must be used in conjunction with GROUPA and GROUPB. All angles involving one atom from
GROUPA, one atom from GROUPB and one atom from GROUPC are calculated. The GROUPA
atoms are assumed to be the central atoms
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
Generated by Doxygen
160
Collective Variables
BETWEEN
HISTOGRAM
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
SWITCH
A switching function that ensures that only angles between atoms that are
within a certain fixed cutoff are calculated. The following provides information
on the switchingfunction that are available.
SWITCHA
A switching function on the distance between the atoms in group A and the
atoms in group B
SWITCHB
A switching function on the distance between the atoms in group A and the
atoms in group B
Examples
The following example instructs plumed to find the average of two angles and to print it to a file
BEGIN_PLUMED_FILE
ANGLES ATOMS1=1,2,3 ATOMS2=4,5,6 MEAN LABEL=a1
PRINT ARG=a1.mean FILE=colvar
The following example tells plumed to calculate all angles involving at least one atom from GROUPA and two atoms
from GROUPB in which the distances are less than 1.0. The number of angles between π4 and 3π
4 is then output
BEGIN_PLUMED_FILE
ANGLES GROUPA=1-10 GROUPB=11-100 BETWEEN={GAUSSIAN LOWER=0.25pi UPPER=0.75pi} SWITCH={GAUSSIAN R_0=1.0} LABEL=
PRINT ARG=a1.between FILE=colvar
This final example instructs plumed to calculate all the angles in the first coordination spheres of the atoms. The
bins for a normalized histogram of the distribution is then output
BEGIN_PLUMED_FILE
ANGLES GROUP=1-38 HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=pi NBINS=20} SWITCH={GAUSSIAN R_0=1.0} LABEL=a1
PRINT ARG=a1.* FILE=colvar
5.5.5
BOND_DIRECTIONS
Generated by Doxygen
5.5 MultiColvar
161
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate the vectors connecting atoms that are within cutoff defined using a switching function.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of vectors calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. All of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set the label for the components. As such by using
the LABEL keyword in the description of the keyword input you can customize the component name. In addition,
you can calculate all of these scalar functions for one particular component of the calculated vector by making
use of the COMPONENT keyword. The first component is used to refer to the norm of the vector. The individual
components can then be referenced using the numbers 2, 3, and so on. So as an example MEAN1={COMPON←ENT=1} calculates the average vector norm. MEAN2={COMPONENT=2} by contrast calculates the mean for all of
the first components of the vectors.
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere in
the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere in the
input file by using the label.vsum
The atoms involved can be specified using
ATOMS
the atoms involved in each of the vectors you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one vector will be calculated for each ATOM keyword you specify
(all ATOM keywords should specify the indices of two atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Generated by Doxygen
Calculate the distance between each distinct pair of atoms in the group
162
Collective Variables
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Compulsory keywords
NN
( default=12 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
VSUM
calculate the norm of the sum of vectors. The final value can be referenced
using label.vsum. You can use multiple instances of this keyword i.e. VSU←M1, VSUM2, VSUM3... The corresponding values are then referenced using
label.vsum-1, label.vsum-2, label.vsum-3...
Examples
5.5.6
BRIDGE
This is part of the multicolvar module
Generated by Doxygen
5.5 MultiColvar
163
Calculate the number of atoms that bridge two parts of a structure
This quantity calculates:
f (x) =
X
sA (rij )sB (rik )
ijk
where the sum over i is over all the ``bridging atoms" and sA and sB are switchingfunction.
The atoms involved can be specified using
BRIDGING_ATOMS
GROUPA
The list of atoms that can form the bridge between the two interesting parts of the structure.
The list of atoms that are in the first interesting part of the structure
GROUPB
The list of atoms that are in the second interesting part of the structure
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
SWITCH
The parameters of the two switchingfunction in the above formula
SWITCHA
The switchingfunction on the distance between bridging atoms and the atoms
in group A
SWITCHB
The switchingfunction on the distance between the bridging atoms and the
atoms in group B
Examples
The following example instructs plumed to calculate the number of water molecules that are bridging between atoms
1-10 and atoms 11-20 and to print the value to a file
BEGIN_PLUMED_FILE
BRIDGE BRIDGING_ATOMS=100-200 GROUPA=1-10 GROUPB=11-20 LABEL=w1
PRINT ARG=a1.mean FILE=colvar
5.5.7
COORDINATIONNUMBER
This is part of the multicolvar module
Generated by Doxygen
164
Collective Variables
Calculate the coordination numbers of atoms so that you can then calculate functions of the distribution of coordination numbers such as the minimum, the number less than a certain quantity and so on.
To make the calculation of coordination numbers differentiable the following function is used:
1−
r−d0
r0
1−
r−d0
r0
s=
n
m
If R_POWER is set, this will use the product of pairwise distance raised to the R_POWER with the coordination
number function defined above. This was used in White and Voth [26] as a way of indirectly biasing radial distribution
functions. Note that in that reference this function is referred to as moments of coordination number, but here we
call them powers to distinguish from the existing MOMENTS keyword of Multicolvars.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
Generated by Doxygen
5.5 MultiColvar
165
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Or alternatively by using
SPECIESA
SPECIESB
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
R_POWER
Multiply the coordination number function by a power of r, as done in White and
Voth (see note above, default: no)
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
Generated by Doxygen
166
Collective Variables
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number of variables more than a certain target value. This quanP
tity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the maximum value. To make this
continuous the maximum
quantity
MAX
is calculated using
MIN
BETWEEN
HISTOGRAM
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
ALT_MIN
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
Generated by Doxygen
5.5 MultiColvar
167
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Examples
The following input tells plumed to calculate the coordination numbers of atoms 1-100 with themselves. The minimum coordination number is then calculated.
BEGIN_PLUMED_FILE
COORDINATIONNUMBER SPECIES=1-100 R_0=1.0 MIN={BETA=0.1}
The following input tells plumed to calculate how many atoms from 1-100 are within 3.0 of each of the atoms from
101-110. In the first 101 is the central atom, in the second 102 is the central atom and so on. The number of
coordination numbers more than 6 is then computed.
BEGIN_PLUMED_FILE
COORDINATIONNUMBER SPECIESA=101-110 SPECIESB=1-100 R_0=3.0 MORE_THAN={RATIONAL R_0=6.0 NN=6 MM=12 D_0=0}
The following input tells plumed to calculate the mean coordination number of all atoms with themselves and its
powers. An explicit cutoff is set for each of 8.
BEGIN_PLUMED_FILE
cn0: COORDINATIONNUMBER SPECIES=1-10
cn1: COORDINATIONNUMBER SPECIES=1-10
cn2: COORDINATIONNUMBER SPECIES=1-10
PRINT ARG=cn0.mean,cn1.mean,cn2.mean
5.5.8
SWITCH={RATIONAL R_0=1.0 D_MAX=8} MEAN
SWITCH={RATIONAL R_0=1.0 D_MAX=8} R_POWER=1 MEAN
SWITCH={RATIONAL R_0=1.0 D_MAX=8} R_POWER=2 MEAN
STRIDE=1 FILE=cn_out
DENSITY
This is part of the multicolvar module
Calculate functions of the density of atoms as a function of the box. This allows one to calculate the number of
atoms in half the box.
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Generated by Doxygen
168
Collective Variables
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Examples
The following example calculates the number of atoms in one half of the simulation box.
BEGIN_PLUMED_FILE
DENSITY SPECIES=1-100 LABEL=d
AROUND ARG=d XLOWER=0.0 XUPPER=0.5 LABEL=d1
PRINT ARG=d1.* FILE=colvar1 FMT=%8.4f
5.5.9
DISTANCES
This is part of the multicolvar module
Calculate the distances between one or many pairs of atoms. You can then calculate functions of the distribution of
distances such as the minimum, the number less than a certain quantity and so on.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
Generated by Doxygen
5.5 MultiColvar
169
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the distances you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one distance will be calculated for each ATOM keyword you specify
(all ATOM keywords should specify the indices of two atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
NUMERICAL_DERIVATIVES
Generated by Doxygen
( default=off ) calculate the derivatives for these quantities numerically
170
NOPBC
Collective Variables
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
ALT_MIN
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
MIN
MAX
min
min
MORE_THAN
BETWEEN
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
is calculated using
LESS_THAN
log
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number of variables more than a certain target value. This quanP
tity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
Generated by Doxygen
5.5 MultiColvar
171
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
(s
ment of a distribution is calculated using N
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
Examples
The following input tells plumed to calculate the distances between atoms 3 and 5 and between atoms 1 and 2 and
to print the minimum for these two distances.
BEGIN_PLUMED_FILE
DISTANCES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
The following input tells plumed to calculate the distances between atoms 3 and 5 and between atoms 1 and 2 and
then to calculate the number of these distances that are less than 0.1 nm. The number of distances less than 0.1nm
is then printed to a file.
BEGIN_PLUMED_FILE
DISTANCES ATOMS1=3,5 ATOMS2=1,2 LABEL=d1 LESS_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.lt0.1
(See also PRINT switchingfunction).
The following input tells plumed to calculate all the distances between atoms 1, 2 and 3 (i.e. the distances between
atoms 1 and 2, atoms 1 and 3 and atoms 2 and 3). The average of these distances is then calculated.
BEGIN_PLUMED_FILE
DISTANCES GROUP=1-3 MEAN LABEL=d1
PRINT ARG=d1.mean
(See also PRINT)
The following input tells plumed to calculate all the distances between the atoms in GROUPA and the atoms in
GROUPB. In other words the distances between atoms 1 and 2 and the distance between atoms 1 and 3. The
number of distances more than 0.1 is then printed to a file.
BEGIN_PLUMED_FILE
DISTANCES GROUPA=1 GROUPB=2,3 MORE_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.gt0.1
Generated by Doxygen
172
Collective Variables
(See also PRINT switchingfunction)
Calculating minimum distances
To calculate and print the minimum distance between two groups of atoms you use the following commands
BEGIN_PLUMED_FILE
d1: DISTANCES GROUPA=1-10 GROUPB=11-20 MIN={BETA=500.}
PRINT ARG=d1.min FILE=colvar STRIDE=10
(see DISTANCES and PRINT)
In order to ensure that the minimum value has continuous derivatives we use the following function:
β
s=
log
P
i
exp
β
si
where β is a user specified parameter.
This input is used rather than a separate MINDIST colvar so that the same routine and the same input style
can be used to calculate minimum coordination numbers (see COORDINATIONNUMBER), minimum angles (see
ANGLES) and many other variables.
This new way of calculating mindist is part of plumed 2's multicolvar functionality. These special actions allow you
to calculate multiple functions of a distribution of simple collective variables. As an example you can calculate the
number of distances less than 1.0, the minimum distance, the number of distances more than 2.0 and the number
of distances between 1.0 and 2.0 by using the following command:
BEGIN_PLUMED_FILE
DISTANCES ...
GROUPA=1-10 GROUPB=11-20
LESS_THAN={RATIONAL R_0=1.0}
MORE_THAN={RATIONAL R_0=2.0}
BETWEEN={GAUSSIAN LOWER=1.0 UPPER=2.0}
MIN={BETA=500.}
... DISTANCES
PRINT ARG=d1.lessthan,d1.morethan,d1.between,d1.min FILE=colvar STRIDE=10
(see DISTANCES and PRINT)
A calculation performed this way is fast because the expensive part of the calculation - the calculation of all the
distances - is only done once per step. Furthermore, it can be made faster by using the TOL keyword to discard
those distance that make only a small contributions to the final values together with the NL_STRIDE keyword, which
ensures that the distances that make only a small contribution to the final values aren't calculated at every step.
5.5.10
FCCUBIC
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Generated by Doxygen
5.5 MultiColvar
173
Measure how similar the environment around atoms is to that found in a FCC structure.
This CV was introduced in this article [27] and again in this article [28] This CV essentially determines whether the
environment around any given atom is similar to that found in the FCC structure or not. The function that is used to
make this determination is as follows:
P
si =
i6=j
n h
(xij yij )4 +(xij zij )4 +(yij zij )4
−
σ(rij ) a
r8
P ij
i6=j σ(rij )
α(xij yij zij )4
12
rij
i
o
+b
In this expression xij , yij and zij are the x, y and z components of the vector connecting atom i to atom j and
rij is the magnitude of this vector. σ(rij ) is a switchingfunction that acts on the distance between atom i and atom
j and its inclusion in the numerator and the denominator of the above expression as well as the fact that we are
summing over all of the other atoms in the system ensures that we are calculating an average of the function of xij ,
yij and zij for the atoms in the first coordination sphere around atom i. Lastly, α is a parameter that can be set by
the user, which by default is equal to three. The values of a and b are calculated from α using:
a=
80080
2717 + 16α
and
b=
16(α − 143)
2717 + 16α
This quantity is once again a multicolvar so you can compute it for multiple atoms using a single PLUMED action
and then compute the average value for the atoms in your system, the number of atoms that have an si value that is
more that some target and so on. Notice also that you can rotate the reference frame if you are using a non-standard
unit cell.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
Generated by Doxygen
174
Collective Variables
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Or alternatively by using
SPECIESA
SPECIESB
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D_0
( default=0.0 ) The d_0 parameter of the switching function
R_0
The r_0 parameter of the switching function
PHI
( default=0.0 ) The Euler rotational angle phi
THETA
( default=0.0 ) The Euler rotational angle theta
PSI
( default=0.0 ) The Euler rotational angle psi
ALPHA
( default=3.0 ) The alpha parameter of the angular function
Options
Generated by Doxygen
5.5 MultiColvar
175
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) calculate the sum of the components of the vector rather than the
mean
UNORMALIZED
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the maximum value. To make this
continuous the maximum
quantity
MAX
is calculated using
MIN
BETWEEN
HISTOGRAM
Generated by Doxygen
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
176
Collective Variables
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
ALT_MIN
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
min
Examples
The following input calculates the FCCUBIC parameter for the 64 atoms in the system and then calculates and
prints the average value for this quantity.
BEGIN_PLUMED_FILE
FCCUBIC SPECIES=1-64 SWITCH={RATIONAL D_0=3.0 R_0=1.5} MEAN LABEL=d
PRINT ARG=d.* FILE=colv
5.5.11
HBPAMM_SH
This is part of the pamm module
It is only available if you configure PLUMED with ./configure –enable-modules=pamm . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Number of HBPAMM hydrogen bonds formed by each hydrogen atom in the system
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
Generated by Doxygen
5.5 MultiColvar
177
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The atoms involved can be specified using
HYDROGENS
The list of hydrogen atoms that can form part of a hydrogen bond. The atoms must be specified
using a comma separated list.
SITES
The list of atoms which can be part of a hydrogen bond. When this command is used the set of
atoms that can donate a hydrogen bond is assumed to be the same as the set of atoms that can
form hydrogen bonds. The atoms involved must be specified as a list of labels of MultiColvar or
labels of a MultiColvar functions actions. If you would just like to use the atomic positions you
can use a DENSITY command to specify a group of atoms. Specifying your atomic positions
using labels of other MultiColvar or MultiColvar functions commands is useful, however, as
you can then exploit a much wider variety of functions of the contact matrix as described in
Exploiting contact matrices
Or alternatively by using
DONORS
Generated by Doxygen
The list of atoms which can donate a hydrogen bond. The atoms involved must be specified
as a list of labels of MultiColvar or labels of a MultiColvar functions actions. If you would just
like to use the atomic positions you can use a DENSITY command to specify a group of atoms.
Specifying your atomic positions using labels of other MultiColvar or MultiColvar functions commands is useful, however, as you can then exploit a much wider variety of functions of the
contact matrix as described in Exploiting contact matrices
178
ACCEPTORS
Collective Variables
The list of atoms which can accept a hydrogen bond. The atoms involved must be specified
as a list of labels of MultiColvar or labels of a MultiColvar functions actions. If you would just
like to use the atomic positions you can use a DENSITY command to specify a group of atoms.
Specifying your atomic positions using labels of other MultiColvar or MultiColvar functions commands is useful, however, as you can then exploit a much wider variety of functions of the
contact matrix as described in Exploiting contact matrices
Compulsory keywords
CLUSTERS
the name of the file that contains the definitions of all the kernels for PAMM You can use
multiple instances of this keyword i.e. CLUSTERS1, CLUSTERS2, CLUSTERS3...
REGULARISE
( default=0.001 ) don't allow the denominator to be smaller then this value
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the maximum value. To make this
continuous the maximum
quantity
MAX
is calculated using
MIN
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
Generated by Doxygen
5.5 MultiColvar
BETWEEN
HISTOGRAM
179
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
ALT_MIN
calculate the minimum value. To make this quantity continuous the minimum
P
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
SUM
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
min
Examples
5.5.12
INPLANEDISTANCES
This is part of the multicolvar module
Calculate distances in the plane perpendicular to an axis
Each quantity calculated in this CV uses the positions of two atoms, this indices of which are specified using the
VECTORSTART and VECTOREND keywords, to specify the orientation of a vector, n. The perpendicular distance
between this vector and the position of some third atom is then computed using:
xj = |rj | sin(θj )
where rj is the distance between one of the two atoms that define the vector n and a third atom (atom j ) and where
θj is the angle between the vector n and the vector rj . The xj values for each of the atoms specified using the
Generated by Doxygen
180
Collective Variables
GROUP keyword are calculated. Keywords such as MORE_THAN and LESS_THAN can then be used to calculate
the number of these quantities that are more or less than a given cutoff.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
VECTORSTART
The first atom position that is used to define the normal to the plane of interest. For more
information on how to specify lists of atoms see Groups and Virtual Atoms
VECTOREND
The second atom position that is used to define the normal to the plane of interest. For more
information on how to specify lists of atoms see Groups and Virtual Atoms
Generated by Doxygen
5.5 MultiColvar
181
Or alternatively by using
GROUP
The set of atoms for which you wish to calculate the in plane distance
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
ALT_MIN
calculate the minimum value. To make this quantity continuous the minimum
P
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
MIN
MAX
min
min
is calculated using
LESS_THAN
MORE_THAN
Generated by Doxygen
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
182
Collective Variables
BETWEEN
HISTOGRAM
MOMENTS
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
Examples
The following input can be used to calculate the number of atoms that have indices greater than 3 and less than
101 that are within a cylinder with a radius of 0.3 nm that has its long axis aligned with the vector connecting atoms
1 and 2.
BEGIN_PLUMED_FILE
d1: INPLANEDISTANCES VECTORSTART=1 VECTOREND=2 GROUP=3-100 LESS_THAN={RATIONAL D_0=0.2 R_0=0.1}
PRINT ARG=d1.lessthan FILE=colvar
5.5.13
MOLECULES
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate the vectors connecting a pair of atoms in order to represent the orientation of a molecule.
At its simplest this command can be used to calculate the average length of an internal vector in a collection of
different molecules. When used in conjunction with MutiColvarFunctions in can be used to do a variety of more
complex tasks.
Description of components
Generated by Doxygen
5.5 MultiColvar
183
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of vectors calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. All of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set the label for the components. As such by using
the LABEL keyword in the description of the keyword input you can customize the component name. In addition,
you can calculate all of these scalar functions for one particular component of the calculated vector by making
use of the COMPONENT keyword. The first component is used to refer to the norm of the vector. The individual
components can then be referenced using the numbers 2, 3, and so on. So as an example MEAN1={COMPON←ENT=1} calculates the average vector norm. MEAN2={COMPONENT=2} by contrast calculates the mean for all of
the first components of the vectors.
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere in
the input file by using the label.vmean
The atoms involved can be specified using
MOL
The numerical indices of the atoms in the molecule. The orientation of the molecule is equal to the
vector connecting the first two atoms specified. If a third atom is specified its position is used to specify
where the molecule is. If a third atom is not present the molecule is assumed to be at the center of the
vector connecting the first two atoms. You can use multiple instances of this keyword i.e. MOL1, MOL2,
MOL3...
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
Examples
The following input tells plumed to calculate the distances between two of the atoms in a molecule. This is done for
the same set of atoms four different molecules and the average separation is then calculated.
Generated by Doxygen
184
Collective Variables
BEGIN_PLUMED_FILE
MOLECULES MOL1=1,2 MOL2=3,4 MOL3=5,6 MOL4=7,8 MEAN LABEL=mm
PRINT ARG=mm.mean FILE=colvar
5.5.14
PLANES
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate the plane perpendicular to two vectors in order to represent the orientation of a planar molecule.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of vectors calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. All of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set the label for the components. As such by using
the LABEL keyword in the description of the keyword input you can customize the component name. In addition,
you can calculate all of these scalar functions for one particular component of the calculated vector by making
use of the COMPONENT keyword. The first component is used to refer to the norm of the vector. The individual
components can then be referenced using the numbers 2, 3, and so on. So as an example MEAN1={COMPON←ENT=1} calculates the average vector norm. MEAN2={COMPONENT=2} by contrast calculates the mean for all of
the first components of the vectors.
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere in
the input file by using the label.vmean
The atoms involved can be specified using
MOL
The numerical indices of the atoms in the molecule. If three atoms are specified the orientation of
the molecule is taken as the normal to the plane containing the vector connecting the first and second
atoms and the vector connecting the second and third atoms. If four atoms are specified the orientation
of the molecule is taken as the normal to the plane containing the vector connecting the first and second
atoms and the vector connecting the third and fourth atoms. The molecule is always assumed to lie at
the geometric center for the three/four atoms. You can use multiple instances of this keyword i.e. MOL1,
MOL2, MOL3...
Generated by Doxygen
5.5 MultiColvar
185
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
Examples
5.5.15
Q3
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate 3rd order Steinhardt parameters.
The 3rd order Steinhardt parameters allow us to measure the degree to which the first coordination shell around an
atom is ordered. The Steinhardt parameter for atom, i is complex vector whose components are calculated using
the following formula:
P
q3m (i) =
j
σ(rij )Y3m (rij )
P
j σ(rij )
where Y3m is one of the 3rd order spherical harmonics so m is a number that runs from −3 to +3. The function
σ(rij ) is a switchingfunction that acts on the distance between atoms i and j . The parameters of this function
should be set so that it the function is equal to one when atom j is in the first coordination sphere of atom i and is
zero otherwise.
The Steinhardt parameters can be used to measure the degree of order in the system in a variety of different ways.
The simplest way of measuring whether or not the coordination sphere is ordered is to simply take the norm of the
above vector i.e.
v
u 3
u X
q3m (i)∗ q3m (i)
Q3 (i) = t
m=−3
This norm is small when the coordination shell is disordered and larger when the coordination shell is ordered.
Furthermore, when the keywords LESS_THAN, MIN, MAX, HISTOGRAM, MEAN and so on are used with this
colvar it is the distribution of these normed quantities that is investigated.
Generated by Doxygen
186
Collective Variables
Other measures of order can be taken by averaging the components of the individual q3 vectors individually or by
taking dot products of the q3 vectors on adjacent atoms. More information on these variables can be found in the
documentation for LOCAL_Q3, LOCAL_AVERAGE and NLINKS.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of vectors calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. All of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set the label for the components. As such by using
the LABEL keyword in the description of the keyword input you can customize the component name. In addition,
you can calculate all of these scalar functions for one particular component of the calculated vector by making
use of the COMPONENT keyword. The first component is used to refer to the norm of the vector. The individual
components can then be referenced using the numbers 2, 3, and so on. So as an example MEAN1={COMPON←ENT=1} calculates the average vector norm. MEAN2={COMPONENT=2} by contrast calculates the mean for all of
the first components of the vectors.
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
Generated by Doxygen
5.5 MultiColvar
SPECIES
187
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Or alternatively by using
SPECIESA
SPECIESB
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
NN
( default=12 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
Generated by Doxygen
188
LESS_THAN
MORE_THAN
Collective Variables
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
ment of a distribution is calculated using N
(s
− s)m , where s is the
i
i=1
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MIN
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
ALT_MIN
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the minimum value. To make this quantity continuous the minimum
P
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Generated by Doxygen
5.5 MultiColvar
189
Examples
The following command calculates the average Q3 parameter for the 64 atoms in a box of Lennard Jones and prints
this quantity to a file called colvar:
BEGIN_PLUMED_FILE
Q3 SPECIES=1-64 D_0=1.3 R_0=0.2 MEAN LABEL=q3
PRINT ARG=q3.mean FILE=colvar
The following command calculates the histogram of Q3 parameters for the 64 atoms in a box of Lennard Jones and
prints these quantities to a file called colvar:
BEGIN_PLUMED_FILE
Q3 SPECIES=1-64 D_0=1.3 R_0=0.2 HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1} LABEL=q3
PRINT ARG=q3.* FILE=colvar
The following command could be used to measure the Q3 parameters that describe the arrangement of chlorine
ions around the sodium atoms in sodium chloride. The imagined system here is composed of 64 NaCl formula units
and the atoms are arranged in the input with the 64 Na + ions followed by the 64 Cl − ions. Once again the average
Q3 parameter is calculated and output to a file called colvar
BEGIN_PLUMED_FILE
Q3 SPECIESA=1-64 SPECIESB=65-128 D_0=1.3 R_0=0.2 MEAN LABEL=q3
PRINT ARG=q3.mean FILE=colvar
5.5.16
Q4
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate fourth order Steinhardt parameters.
The fourth order Steinhardt parameters allow us to measure the degree to which the first coordination shell around
an atom is ordered. The Steinhardt parameter for atom, i is complex vector whose components are calculated using
the following formula:
P
q4m (i) =
j
σ(rij )Y4m (rij )
P
j σ(rij )
where Y4m is one of the fourth order spherical harmonics so m is a number that runs from −4 to +4. The function
σ(rij ) is a switchingfunction that acts on the distance between atoms i and j . The parameters of this function
should be set so that it the function is equal to one when atom j is in the first coordination sphere of atom i and is
zero otherwise.
The Steinhardt parameters can be used to measure the degree of order in the system in a variety of different ways.
The simplest way of measuring whether or not the coordination sphere is ordered is to simply take the norm of the
above vector i.e.
Generated by Doxygen
190
Collective Variables
v
u 4
u X
Q4 (i) = t
q4m (i)∗ q4m (i)
m=−4
This norm is small when the coordination shell is disordered and larger when the coordination shell is ordered.
Furthermore, when the keywords LESS_THAN, MIN, MAX, HISTOGRAM, MEAN and so on are used with this
colvar it is the distribution of these normed quantities that is investigated.
Other measures of order can be taken by averaging the components of the individual q4 vectors individually or by
taking dot products of the q4 vectors on adjacent atoms. More information on these variables can be found in the
documentation for LOCAL_Q4, LOCAL_AVERAGE and NLINKS.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of vectors calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. All of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set the label for the components. As such by using
the LABEL keyword in the description of the keyword input you can customize the component name. In addition,
you can calculate all of these scalar functions for one particular component of the calculated vector by making
use of the COMPONENT keyword. The first component is used to refer to the norm of the vector. The individual
components can then be referenced using the numbers 2, 3, and so on. So as an example MEAN1={COMPON←ENT=1} calculates the average vector norm. MEAN2={COMPONENT=2} by contrast calculates the mean for all of
the first components of the vectors.
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated Generated
using one
the
by of
Doxygen
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
5.5 MultiColvar
191
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Or alternatively by using
SPECIESA
SPECIESB
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
NN
( default=12 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
Generated by Doxygen
192
LESS_THAN
MORE_THAN
Collective Variables
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number of variables more than a certain target value. This quanP
tity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
(s
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MIN
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
ALT_MIN
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Generated by Doxygen
5.5 MultiColvar
193
Examples
The following command calculates the average Q4 parameter for the 64 atoms in a box of Lennard Jones and prints
this quantity to a file called colvar:
BEGIN_PLUMED_FILE
Q4 SPECIES=1-64 D_0=1.3 R_0=0.2 MEAN LABEL=q4
PRINT ARG=q4.mean FILE=colvar
The following command calculates the histogram of Q4 parameters for the 64 atoms in a box of Lennard Jones and
prints these quantities to a file called colvar:
BEGIN_PLUMED_FILE
Q4 SPECIES=1-64 D_0=1.3 R_0=0.2 HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1} LABEL=q4
PRINT ARG=q4.* FILE=colvar
The following command could be used to measure the Q4 parameters that describe the arrangement of chlorine
ions around the sodium atoms in sodium chloride. The imagined system here is composed of 64 NaCl formula units
and the atoms are arranged in the input with the 64 Na + ions followed by the 64 Cl − ions. Once again the average
Q4 parameter is calculated and output to a file called colvar
BEGIN_PLUMED_FILE
Q4 SPECIESA=1-64 SPECIESB=65-128 D_0=1.3 R_0=0.2 MEAN LABEL=q4
PRINT ARG=q4.mean FILE=colvar
5.5.17
Q6
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate sixth order Steinhardt parameters.
The sixth order Steinhardt parameters allow us to measure the degree to which the first coordination shell around
an atom is ordered. The Steinhardt parameter for atom, i is complex vector whose components are calculated using
the following formula:
P
q6m (i) =
j
σ(rij )Y6m (rij )
P
j σ(rij )
where Y6m is one of the sixth order spherical harmonics so m is a number that runs from −6 to +6. The function
σ(rij ) is a switchingfunction that acts on the distance between atoms i and j . The parameters of this function
should be set so that it the function is equal to one when atom j is in the first coordination sphere of atom i and is
zero otherwise.
The Steinhardt parameters can be used to measure the degree of order in the system in a variety of different ways.
The simplest way of measuring whether or not the coordination sphere is ordered is to simply take the norm of the
above vector i.e.
Generated by Doxygen
194
Collective Variables
v
u 6
u X
Q6 (i) = t
q6m (i)∗ q6m (i)
m=−6
This norm is small when the coordination shell is disordered and larger when the coordination shell is ordered.
Furthermore, when the keywords LESS_THAN, MIN, MAX, HISTOGRAM, MEAN and so on are used with this
colvar it is the distribution of these normed quantities that is investigated.
Other measures of order can be taken by averaging the components of the individual q6 vectors individually or by
taking dot products of the q6 vectors on adjacent atoms. More information on these variables can be found in the
documentation for LOCAL_Q6, LOCAL_AVERAGE and NLINKS.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of vectors calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. All of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set the label for the components. As such by using
the LABEL keyword in the description of the keyword input you can customize the component name. In addition,
you can calculate all of these scalar functions for one particular component of the calculated vector by making
use of the COMPONENT keyword. The first component is used to refer to the norm of the vector. The individual
components can then be referenced using the numbers 2, 3, and so on. So as an example MEAN1={COMPON←ENT=1} calculates the average vector norm. MEAN2={COMPONENT=2} by contrast calculates the mean for all of
the first components of the vectors.
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated Generated
using one
the
by of
Doxygen
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
5.5 MultiColvar
195
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Or alternatively by using
SPECIESA
SPECIESB
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
NN
( default=12 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
Generated by Doxygen
196
LESS_THAN
MORE_THAN
Collective Variables
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number of variables more than a certain target value. This quanP
tity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
(s
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MIN
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
ALT_MIN
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Generated by Doxygen
5.5 MultiColvar
197
Examples
The following command calculates the average Q6 parameter for the 64 atoms in a box of Lennard Jones and prints
this quantity to a file called colvar:
BEGIN_PLUMED_FILE
Q6 SPECIES=1-64 D_0=1.3 R_0=0.2 MEAN LABEL=q6
PRINT ARG=q6.mean FILE=colvar
The following command calculates the histogram of Q6 parameters for the 64 atoms in a box of Lennard Jones and
prints these quantities to a file called colvar:
BEGIN_PLUMED_FILE
Q6 SPECIES=1-64 D_0=1.3 R_0=0.2 HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1} LABEL=q6
PRINT ARG=q6.* FILE=colvar
The following command could be used to measure the Q6 parameters that describe the arrangement of chlorine
ions around the sodium atoms in sodium chloride. The imagined system here is composed of 64 NaCl formula units
and the atoms are arranged in the input with the 64 Na + ions followed by the 64 Cl − ions. Once again the average
Q6 parameter is calculated and output to a file called colvar
BEGIN_PLUMED_FILE
Q6 SPECIESA=1-64 SPECIESB=65-128 D_0=1.3 R_0=0.2 MEAN LABEL=q6
PRINT ARG=q6.mean FILE=colvar
5.5.18
SIMPLECUBIC
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate whether or not the coordination spheres of atoms are arranged as they would be in a simple cubic
structure.
We can measure how similar the environment around atom i is to a simple cubic structure is by evaluating the
following quantity:
P
si =
i6=j
σ(rij )
P
i6=j
h
4
4
x4ij +yij
+zij
4
rij
i
σ(rij )
In this expression xij , yij and zij are the x, y and z components of the vector connecting atom i to atom j and
rij is the magnitude of this vector. σ(rij ) is a switchingfunction that acts on the distance between atom i and atom
j and its inclusion in the numerator and the denominator of the above expression as well as the fact that we are
summing over all of the other atoms in the system ensures that we are calculating an average of the function of xij ,
yij and zij for the atoms in the first coordination sphere around atom i. This quantity is once again a multicolvar so
you can compute it for multiple atoms using a single PLUMED action and then compute the average value for the
atoms in your system, the number of atoms that have an si value that is more that some target and so on. Notice
also that you can rotate the reference frame if you are using a non-standard unit cell.
Generated by Doxygen
198
Collective Variables
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Generated by Doxygen
5.5 MultiColvar
199
Or alternatively by using
SPECIESA
SPECIESB
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D_0
( default=0.0 ) The d_0 parameter of the switching function
R_0
The r_0 parameter of the switching function
PHI
( default=0.0 ) The Euler rotational angle phi
THETA
( default=0.0 ) The Euler rotational angle theta
PSI
( default=0.0 ) The Euler rotational angle psi
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) calculate the sum of the components of the vector rather than the
mean
UNORMALIZED
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
Generated by Doxygen
200
LESS_THAN
MAX
Collective Variables
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the maximum value. To make this
continuous the maximum
quantity
is calculated using
MIN
BETWEEN
HISTOGRAM
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
(s
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
ALT_MIN
calculate the minimum value. To make this quantity continuous the minimum
P
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
min
Examples
The following input tells plumed to calculate the simple cubic parameter for the atoms 1-100 with themselves. The
mean value is then calculated.
Generated by Doxygen
5.5 MultiColvar
201
BEGIN_PLUMED_FILE
SIMPLECUBIC SPECIES=1-100 R_0=1.0 MEAN
The following input tells plumed to look at the ways atoms 1-100 are within 3.0 are arranged about atoms from
101-110. The number of simple cubic parameters that are greater than 0.8 is then output
BEGIN_PLUMED_FILE
SIMPLECUBIC SPECIESA=101-110 SPECIESB=1-100 R_0=3.0 MORE_THAN={RATIONAL R_0=0.8 NN=6 MM=12 D_0=0}
5.5.19
TETRAHEDRAL
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate the degree to which the environment about ions has a tetrahedral order.
We can measure the degree to which the atoms in the first coordination shell around any atom, i is is arranged like
a tetrahedron using the following function.
#
"
X
1
(xij − yij − zij )3
(−xij + yij − zij )3
(−xij − yij + zij )3
(xij + yij + zij )3
s(i) = P
+
+
+
σ(rij )
3
3
3
3
rij
rij
rij
rij
j σ(rij ) j
Here rij is the magnitude of the vector connecting atom i to atom j and xij , yij and zij are its three components.
The function σ(rij ) is a switchingfunction that acts on the distance between atoms i and j . The parameters of this
function should be set so that the function is equal to one when atom j is in the first coordination sphere of atom i
and is zero otherwise.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Generated by Doxygen
202
Collective Variables
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Or alternatively by using
SPECIESA
SPECIESB
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
Generated by Doxygen
5.5 MultiColvar
203
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D_0
( default=0.0 ) The d_0 parameter of the switching function
R_0
The r_0 parameter of the switching function
PHI
( default=0.0 ) The Euler rotational angle phi
THETA
( default=0.0 ) The Euler rotational angle theta
PSI
( default=0.0 ) The Euler rotational angle psi
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) calculate the sum of the components of the vector rather than the
mean
UNORMALIZED
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the maximum value. To make this
continuous the maximum
quantity
MAX
is calculated using
MIN
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
Generated by Doxygen
204
Collective Variables
BETWEEN
HISTOGRAM
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
ALT_MIN
calculate the minimum value. To make this quantity continuous the minimum
P
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
min
Examples
The following command calculates the average value of the TETRAHEDRAL parameter for a set of 64 atoms all of
the same type and outputs this quantity to a file called colvar.
BEGIN_PLUMED_FILE
tt: TETRAHEDRAL SPECIES=1-64 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN
PRINT ARG=tt.mean FILE=colvar
The following command calculates the number of TETRAHEDRAL parameters that are greater than 0.8 in a set of
10 atoms. In this calculation it is assumed that there are two atom types A and B and that the first coordination
sphere of the 10 atoms of type A contains atoms of type B. The formula above is thus calculated for ten different A
atoms and within it the sum over j runs over 40 atoms of type B that could be in the first coordination sphere.
BEGIN_PLUMED_FILE
tt: TETRAHEDRAL SPECIESA=1-10 SPECIESB=11-40 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MORE_THAN={RATIONAL R_0=0.8}
PRINT ARG=tt.* FILE=colvar
5.5.20
TORSIONS
Generated by Doxygen
5.5 MultiColvar
205
This is part of the multicolvar module
Calculate whether or not a set of torsional angles are within a particular range.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one of
the formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the torsion angles you wish to calculate. Keywords like ATOMS1, A←TOMS2, ATOMS3,... should be listed and one torsion will be calculated for each ATOM keyword
you specify (all ATOM keywords should provide the indices of four atoms). The eventual number of
quantities calculated by this action will depend on what functions of the distribution you choose to
calculate. You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
Generated by Doxygen
206
Collective Variables
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
Examples
The following provides an example of the input for the TORSIONS command
BEGIN_PLUMED_FILE
TORSIONS ...
ATOMS1=168,170,172,188
ATOMS2=170,172,188,190
ATOMS3=188,190,192,230
LABEL=ab
... TORSIONS
PRINT ARG=ab.* FILE=colvar STRIDE=10
Writing out the atoms involved in all the torsion angles in this way can be rather tedious. Thankfully if you are working
with protein you can avoid this by using the MOLINFO command. PLUMED uses the pdb file that you provide to
this command to learn about the topology of the protein molecule. This means that you can specify torsion angles
using the following syntax:
BEGIN_PLUMED_FILE
MOLINFO MOLTYPE=protein STRUCTURE=myprotein.pdb
TORSIONS ...
ATOMS1=@phi-3
ATOMS2=@psi-3
ATOMS3=@phi-4
LABEL=ab
... TORSIONS
PRINT ARG=ab FILE=colvar STRIDE=10
Here, @phi-3 tells plumed that you would like to calculate the φ angle in the third residue of the protein. Similarly
@psi-4 tells plumed that you want to calculate the ψ angle of the fourth residue of the protein.
5.5.21
XANGLES
This is part of the multicolvar module
Calculate the angles between the vector connecting two atoms and the x axis.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
Generated by Doxygen
5.5 MultiColvar
207
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the angles you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one angle will be calculated for each ATOM keyword you specify
(all ATOM keywords should specify the indices of two atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Or alternatively by using
Generated by Doxygen
Calculate the distance between each distinct pair of atoms in the group
208
Collective Variables
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
si
is calculated using
= β log i exp β The value of β in this function is
ALT_MIN
MEAN
MIN
LESS_THAN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
Generated by Doxygen
5.5 MultiColvar
BETWEEN
HISTOGRAM
209
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
SWITCH
A switching function that ensures that only angles are only computed when
atoms are within are within a certain fixed cutoff. The following provides information on the switchingfunction that are available.
Examples
The following input tells plumed to calculate the angles between the x-axis and the vector connecting atom 3 to
atom 5 and between the x-axis and the vector connecting atom 1 to atom 2. The minimum of these two quantities
is then
BEGIN_PLUMED_FILE
XANGLES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
5.5.22
XDISTANCES
This is part of the multicolvar module
Calculate the x components of the vectors connecting one or many pairs of atoms. You can then calculate functions
of the distribution of values such as the minimum, the number less than a certain quantity and so on.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
Generated by Doxygen
210
Collective Variables
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the distances you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one distance will be calculated for each ATOM keyword you specify
(all ATOM keywords should specify the indices of two atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
Generated by Doxygen
5.5 MultiColvar
211
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
si
is calculated using
= β log i exp β The value of β in this function is
ALT_MIN
MEAN
MIN
LESS_THAN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
Generated by Doxygen
212
BETWEEN
HISTOGRAM
MOMENTS
Collective Variables
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
Examples
The following input tells plumed to calculate the x-component of the vector connecting atom 3 to atom 5 and the
x-component of the vector connecting atom 1 to atom 2. The minimum of these two quantities is then printed
BEGIN_PLUMED_FILE
XDISTANCES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
The following input tells plumed to calculate the x-component of the vector connecting atom 3 to atom 5 and the
x-component of the vector connecting atom 1 to atom 2. The number of values that are less than 0.1nm is then
printed to a file.
BEGIN_PLUMED_FILE
XDISTANCES ATOMS1=3,5 ATOMS2=1,2 LABEL=d1 LESS_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.lt0.1
(See also PRINT switchingfunction).
The following input tells plumed to calculate the x-components of all the distinct vectors that can be created between
atoms 1, 2 and 3 (i.e. the vectors between atoms 1 and 2, atoms 1 and 3 and atoms 2 and 3). The average of these
quantities is then calculated.
BEGIN_PLUMED_FILE
XDISTANCES GROUP=1-3 AVERAGE LABEL=d1
PRINT ARG=d1.average
(See also PRINT)
The following input tells plumed to calculate all the vectors connecting the the atoms in GROUPA to the atoms in
GROUPB. In other words the vector between atoms 1 and 2 and the vector between atoms 1 and 3. The number of
values more than 0.1 is then printed to a file.
BEGIN_PLUMED_FILE
XDISTANCES GROUPA=1 GROUPB=2,3 MORE_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.gt0.1
(See also PRINT switchingfunction)
Generated by Doxygen
5.5 MultiColvar
5.5.23
213
XYDISTANCES
This is part of the multicolvar module
Calculate distance between a pair of atoms neglecting the z-component.
You can then calculate functions of the distribution of values such as the minimum, the number less than a certain
quantity and so on.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
Generated by Doxygen
214
ATOMS
Collective Variables
the atoms involved in each of the distances you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one distance will be calculated for each ATOM keyword you specify
(all ATOM keywords should specify the indices of two atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
is calculated using
ALT_MIN
MEAN
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
Generated by Doxygen
5.5 MultiColvar
MIN
LESS_THAN
LOWEST
215
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
(s
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
Examples
The following input tells plumed to calculate the projection of the length of the vector connecting atom 3 to atom 5
projected in the xy-plane and the projection of the length of the vector the vector connecting atom 1 to atom 2 in the
xy-plane. The minimum of these two quantities is then printed
BEGIN_PLUMED_FILE
XYDISTANCES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
Generated by Doxygen
216
5.5.24
Collective Variables
XYTORSIONS
This is part of the multicolvar module
Calculate the torsional angle around the x axis from the positive y direction.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one of
the formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the torsion angles you wish to calculate. Keywords like ATOMS1, A←TOMS2, ATOMS3,... should be listed and one torsion will be calculated for each ATOM keyword
you specify (all ATOM keywords should specify the indices of two atoms). The eventual number of
quantities calculated by this action will depend on what functions of the distribution you choose to
calculate. You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Generated by Doxygen
5.5 MultiColvar
217
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
is calculated using
ALT_MIN
MEAN
MIN
LOWEST
HIGHEST
Generated by Doxygen
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
218
Collective Variables
BETWEEN
HISTOGRAM
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
(s
ment of a distribution is calculated using N
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
SWITCH
A switching function that ensures that only angles are only computed when
atoms are within are within a certain fixed cutoff. The following provides information on the switchingfunction that are available.
Examples
The following input tells plumed to calculate the angle around the x direction between the positive y-axis and the
vector connecting atom 3 to atom 5 and the angle around the x direction between the positive y axis and the vector
connecting atom 1 to atom 2. The minimum of these two quantities is then output
BEGIN_PLUMED_FILE
XYTORSIONS ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
5.5.25
XZDISTANCES
This is part of the multicolvar module
Calculate distance between a pair of atoms neglecting the y-component.
You can then calculate functions of the distribution of values such as the minimum, the number less than a certain
quantity and so on.
Description of components
Generated by Doxygen
5.5 MultiColvar
219
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the distances you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one distance will be calculated for each ATOM keyword you specify
(all ATOM keywords should specify the indices of two atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Generated by Doxygen
Calculate the distance between each distinct pair of atoms in the group
220
Collective Variables
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
si
is calculated using
= β log i exp β The value of β in this function is
ALT_MIN
MEAN
MIN
LESS_THAN
LOWEST
HIGHEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Generated by Doxygen
5.5 MultiColvar
221
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
Examples
The following input tells plumed to calculate the projection of the length of the vector connecting atom 3 to atom 5
projected in the xz-plane and the projection of the length of the vector the vector connecting atom 1 to atom 2 in the
xz-plane. The minimum of these two quantities is then printed
BEGIN_PLUMED_FILE
XZDISTANCES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
5.5.26
XZTORSIONS
This is part of the multicolvar module
Calculate the torsional angle around the x axis from the positive z direction.
Description of components
Generated by Doxygen
222
Collective Variables
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one of
the formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the torsion angles you wish to calculate. Keywords like ATOMS1, A←TOMS2, ATOMS3,... should be listed and one torsion will be calculated for each ATOM keyword
you specify (all ATOM keywords should specify the indices of two atoms). The eventual number of
quantities calculated by this action will depend on what functions of the distribution you choose to
calculate. You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
Generated by Doxygen
5.5 MultiColvar
GROUPB
223
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
si
is calculated using
= β log i exp β The value of β in this function is
ALT_MIN
MEAN
MIN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
Generated by Doxygen
224
Collective Variables
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
SWITCH
A switching function that ensures that only angles are only computed when
atoms are within are within a certain fixed cutoff. The following provides information on the switchingfunction that are available.
Examples
The following input tells plumed to calculate the angle around the x direction between the positive z-axis and the
vector connecting atom 3 to atom 5 and the angle around the x direction between the positive z direction and the
vector connecting atom 1 to atom 2. The minimum of these two quantities is then output
BEGIN_PLUMED_FILE
XZTORSIONS ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
5.5.27
YANGLES
This is part of the multicolvar module
Calculate the angles between the vector connecting two atoms and the y axis.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Generated by Doxygen
5.5 MultiColvar
225
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the angles you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one angle will be calculated for each ATOM keyword you specify
(all ATOM keywords should specify the indices of two atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
Generated by Doxygen
226
Collective Variables
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
si
is calculated using
= β log i exp β The value of β in this function is
ALT_MIN
MEAN
MIN
LESS_THAN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
Generated by Doxygen
5.5 MultiColvar
227
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
(s
ment of a distribution is calculated using N
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
SWITCH
A switching function that ensures that only angles are only computed when
atoms are within are within a certain fixed cutoff. The following provides information on the switchingfunction that are available.
Examples
The following input tells plumed to calculate the angles between the y-axis and the vector connecting atom 3 to
atom 5 and between the y-axis and the vector connecting atom 1 to atom 2. The minimum of these two quantities
is then
BEGIN_PLUMED_FILE
YANGLES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
5.5.28
YDISTANCES
This is part of the multicolvar module
Calculate the y components of the vectors connecting one or many pairs of atoms. You can then calculate functions
of the distribution of values such as the minimum, the number less than a certain quantity and so on.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
Generated by Doxygen
228
Collective Variables
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the distances you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one distance will be calculated for each ATOM keyword you specify
(all ATOM keywords should specify the indices of two atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Generated by Doxygen
5.5 MultiColvar
229
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
is calculated using
= β log i exp sβi The value of β in this function is
ALT_MIN
MEAN
MIN
LESS_THAN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MORE_THAN
calculate the number of variables more than a certain target value. This quanP
tity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
Generated by Doxygen
230
Collective Variables
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
(s
ment of a distribution is calculated using N
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
Examples
The following input tells plumed to calculate the y-component of the vector connecting atom 3 to atom 5 and the
y-component of the vector connecting atom 1 to atom 2. The minimum of these two quantities is then printed
BEGIN_PLUMED_FILE
YDISTANCES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
The following input tells plumed to calculate the y-component of the vector connecting atom 3 to atom 5 and the
y-component of the vector connecting atom 1 to atom 2. The number of values that are less than 0.1nm is then
printed to a file.
BEGIN_PLUMED_FILE
YDISTANCES ATOMS1=3,5 ATOMS2=1,2 LABEL=d1 LESS_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.lt0.1
(See also PRINT switchingfunction).
The following input tells plumed to calculate the y-components of all the distinct vectors that can be created between
atoms 1, 2 and 3 (i.e. the vectors between atoms 1 and 2, atoms 1 and 3 and atoms 2 and 3). The average of these
quantities is then calculated.
BEGIN_PLUMED_FILE
YDISTANCES GROUP=1-3 AVERAGE LABEL=d1
PRINT ARG=d1.average
(See also PRINT)
The following input tells plumed to calculate all the vectors connecting the the atoms in GROUPA to the atoms in
GROUPB. In other words the vector between atoms 1 and 2 and the vector between atoms 1 and 3. The number of
values more than 0.1 is then printed to a file.
BEGIN_PLUMED_FILE
YDISTANCES GROUPA=1 GROUPB=2,3 MORE_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.gt0.1
(See also PRINT switchingfunction)
5.5.29
YXTORSIONS
Generated by Doxygen
5.5 MultiColvar
231
This is part of the multicolvar module
Calculate the torsional angle around the y axis from the positive x direction.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one of
the formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the torsion angles you wish to calculate. Keywords like ATOMS1, A←TOMS2, ATOMS3,... should be listed and one torsion will be calculated for each ATOM keyword
you specify (all ATOM keywords should specify the indices of two atoms). The eventual number of
quantities calculated by this action will depend on what functions of the distribution you choose to
calculate. You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
Generated by Doxygen
232
Collective Variables
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
si
is calculated using
= β log i exp β The value of β in this function is
ALT_MIN
MEAN
MIN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
Generated by Doxygen
5.5 MultiColvar
233
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
(s
ment of a distribution is calculated using N
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
SWITCH
A switching function that ensures that only angles are only computed when
atoms are within are within a certain fixed cutoff. The following provides information on the switchingfunction that are available.
Examples
The following input tells plumed to calculate the angle around the y direction between the positive x-direction and
the vector connecting atom 3 to atom 5 and the angle around the y direction between the positive x axis and the
vector connecting atom 1 to atom 2. The minimum of these two quantities is then output
BEGIN_PLUMED_FILE
YXTORSIONS ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
5.5.30
YZDISTANCES
This is part of the multicolvar module
Calculate distance between a pair of atoms neglecting the x-component.
You can then calculate functions of the distribution of values such as the minimum, the number less than a certain
quantity and so on.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
Generated by Doxygen
234
Collective Variables
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the distances you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one distance will be calculated for each ATOM keyword you specify
(all ATOM keywords should specify the indices of two atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
Generated by Doxygen
5.5 MultiColvar
235
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
si
is calculated using
= β log i exp β The value of β in this function is
ALT_MIN
MEAN
MIN
LESS_THAN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
Generated by Doxygen
236
Collective Variables
BETWEEN
HISTOGRAM
MOMENTS
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
Examples
The following input tells plumed to calculate the projection of the length of the vector connecting atom 3 to atom 5
in the yz-plane and the projection of the length of the vector the vector connecting atom 1 to atom 2 in the yz-plane.
The minimum of these two quantities is then printed
BEGIN_PLUMED_FILE
YZDISTANCES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
5.5.31
YZTORSIONS
This is part of the multicolvar module
Calculate the torsional angle around the y axis from the positive z direction.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
Generated by Doxygen
5.5 MultiColvar
237
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one of
the formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the torsion angles you wish to calculate. Keywords like ATOMS1, A←TOMS2, ATOMS3,... should be listed and one torsion will be calculated for each ATOM keyword
you specify (all ATOM keywords should specify the indices of two atoms). The eventual number of
quantities calculated by this action will depend on what functions of the distribution you choose to
calculate. You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Generated by Doxygen
238
Collective Variables
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
is calculated using
= β log i exp sβi The value of β in this function is
ALT_MIN
MEAN
MIN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
Generated by Doxygen
5.5 MultiColvar
239
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
SWITCH
A switching function that ensures that only angles are only computed when
atoms are within are within a certain fixed cutoff. The following provides information on the switchingfunction that are available.
Examples
The following input tells plumed to calculate the angle around the y direction between the positive z-direction and
the vector connecting atom 3 to atom 5 and the angle around the y direction between the positive z direction and
the vector connecting atom 1 to atom 2. The minimum of these two quantities is then output
BEGIN_PLUMED_FILE
YZTORSIONS ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
5.5.32
ZANGLES
This is part of the multicolvar module
Calculate the angles between the vector connecting two atoms and the z axis.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Generated by Doxygen
240
Collective Variables
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the angles you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one angle will be calculated for each ATOM keyword you specify
(all ATOM keywords should specify the indices of two atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
Generated by Doxygen
5.5 MultiColvar
241
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
si
is calculated using
= β log i exp β The value of β in this function is
ALT_MIN
MEAN
MIN
LESS_THAN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
Generated by Doxygen
242
Collective Variables
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
(s
ment of a distribution is calculated using N
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
SWITCH
A switching function that ensures that only angles are only computed when
atoms are within are within a certain fixed cutoff. The following provides information on the switchingfunction that are available.
Examples
The following input tells plumed to calculate the angles between the z-axis and the vector connecting atom 3 to
atom 5 and between the z-axis and the vector connecting atom 1 to atom 2. The minimum of these two quantities
is then
BEGIN_PLUMED_FILE
ZANGLES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
5.5.33
ZDISTANCES
This is part of the multicolvar module
Calculate the z components of the vectors connecting one or many pairs of atoms. You can then calculate functions
of the distribution of values such as the minimum, the number less than a certain quantity and so on.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
Generated by Doxygen
5.5 MultiColvar
243
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the distances you wish to calculate. Keywords like ATOMS1, ATOMS2,
ATOMS3,... should be listed and one distance will be calculated for each ATOM keyword you specify
(all ATOM keywords should specify the indices of two atoms). The eventual number of quantities
calculated by this action will depend on what functions of the distribution you choose to calculate.
You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Generated by Doxygen
244
Collective Variables
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
is calculated using
= β log i exp sβi The value of β in this function is
ALT_MIN
MEAN
MIN
LESS_THAN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MORE_THAN
calculate the number of variables more than a certain target value. This quanP
tity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
Generated by Doxygen
5.5 MultiColvar
245
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
(s
ment of a distribution is calculated using N
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
Examples
The following input tells plumed to calculate the z-component of the vector connecting atom 3 to atom 5 and the
z-component of the vector connecting atom 1 to atom 2. The minimum of these two quantities is then printed
BEGIN_PLUMED_FILE
ZDISTANCES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
The following input tells plumed to calculate the z-component of the vector connecting atom 3 to atom 5 and the
z-component of the vector connecting atom 1 to atom 2. The number of values that are less than 0.1nm is then
printed to a file.
BEGIN_PLUMED_FILE
ZDISTANCES ATOMS1=3,5 ATOMS2=1,2 LABEL=d1 LESS_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.lt0.1
(See also PRINT switchingfunction).
The following input tells plumed to calculate the z-components of all the distinct vectors that can be created between
atoms 1, 2 and 3 (i.e. the vectors between atoms 1 and 2, atoms 1 and 3 and atoms 2 and 3). The average of these
quantities is then calculated.
BEGIN_PLUMED_FILE
ZDISTANCES GROUP=1-3 AVERAGE LABEL=d1
PRINT ARG=d1.average
(See also PRINT)
The following input tells plumed to calculate all the vectors connecting the the atoms in GROUPA to the atoms in
GROUPB. In other words the vector between atoms 1 and 2 and the vector between atoms 1 and 3. The number of
values more than 0.1 is then printed to a file.
BEGIN_PLUMED_FILE
ZDISTANCES GROUPA=1 GROUPB=2,3 MORE_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.gt0.1
(See also PRINT switchingfunction)
5.5.34
ZXTORSIONS
Generated by Doxygen
246
Collective Variables
This is part of the multicolvar module
Calculate the torsional angle around the z axis from the positive x direction.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one of
the formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the torsion angles you wish to calculate. Keywords like ATOMS1, A←TOMS2, ATOMS3,... should be listed and one torsion will be calculated for each ATOM keyword
you specify (all ATOM keywords should specify the indices of two atoms). The eventual number of
quantities calculated by this action will depend on what functions of the distribution you choose to
calculate. You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
Generated by Doxygen
5.5 MultiColvar
247
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
si
is calculated using
= β log i exp β The value of β in this function is
ALT_MIN
MEAN
MIN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
Generated by Doxygen
248
Collective Variables
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
(s
ment of a distribution is calculated using N
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
SWITCH
A switching function that ensures that only angles are only computed when
atoms are within are within a certain fixed cutoff. The following provides information on the switchingfunction that are available.
Examples
The following input tells plumed to calculate the angle around the z direction between the positive x-direction and
the vector connecting atom 3 to atom 5 and the angle around the z direction between the positive x-direction and
the vector connecting atom 1 to atom 2. The minimum of these two quantities is then output
BEGIN_PLUMED_FILE
ZXTORSIONS ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
5.5.35
ZYTORSIONS
This is part of the multicolvar module
Calculate the torsional angle around the z axis from the positive y direction.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
Generated by Doxygen
5.5 MultiColvar
249
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one of
the formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
The atoms involved can be specified using
ATOMS
the atoms involved in each of the torsion angles you wish to calculate. Keywords like ATOMS1, A←TOMS2, ATOMS3,... should be listed and one torsion will be calculated for each ATOM keyword
you specify (all ATOM keywords should specify the indices of two atoms). The eventual number of
quantities calculated by this action will depend on what functions of the distribution you choose to
calculate. You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2, ATOMS3...
Or alternatively by using
GROUP
Calculate the distance between each distinct pair of atoms in the group
Or alternatively by using
GROUPA
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPB.
GROUPB
Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjunction with GROUPA.
Options
Generated by Doxygen
250
Collective Variables
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MAX
calculate the maximum value. To make this
continuous the maximum
quantity
P
si
is calculated using
= β log i exp β The value of β in this function is
ALT_MIN
MEAN
MIN
LOWEST
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
Generated by Doxygen
5.5 MultiColvar
251
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
SWITCH
A switching function that ensures that only angles are only computed when
atoms are within are within a certain fixed cutoff. The following provides information on the switchingfunction that are available.
Examples
The following input tells plumed to calculate the angle around the z direction between the positive y-axis and the
vector connecting atom 3 to atom 5 and the angle around the z direction between the positive y axis and the vector
connecting atom 1 to atom 2. The minimum of these two quantities is then output
BEGIN_PLUMED_FILE
ZYTORSIONS ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min
(See also PRINT).
5.5.36
MFILTER_BETWEEN
This is part of the multicolvar module
This action can be used to filter the colvar values calculated by a MultiColvar so that one can compute the mean
and so on for only those multicolvars within a certain range.
This action can be used to create a dynamic group of atom based on the value of a multicolvar. In this action a
multicolvar is within the dynamic group if its value lies in a particular range. In actuality a weight, wi is ascribed to
each colvar, si calculated by a multicolvar and this weight measures the degree to which a colvar is a member of
the group. This weight is calculated using a histogrambead so it is given by:
Z
wi =
b
K
a
s − si
w
where a, b and w are parameters. If one calculates a function of the set of multicolvars these weights are included
in the calculation. As such if one calculates the MEAN, µ of a filtered multicolvar what is computed is the following:
P
wi si
µ = Pi
i wi
One is thus calculating the mean for those colvars that are within the range of interest.
Generated by Doxygen
252
Collective Variables
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere in
the input file by using the label.vmean
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
LOWER
the lower boundary for the range of interest
UPPER
the upper boundary for the range of interest
SMEAR
( default=0.5 ) the amount by which to smear the value for kernel density estimation
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Generated by Doxygen
5.5 MultiColvar
253
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MIN
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
MAX
min
is calculated using
ALT_MIN
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
BEAD
This keywords is used if you want to employ an alternative to the function defined above. The following provides information on the histogrambead that are
available. When this keyword is present you no longer need the LOWER, U←PPER and SMEAR keywords.
Examples
The example shown below calculates the mean for those distances that are between 0 and 3 nm in length
BEGIN_PLUMED_FILE
DISTANCES GROUPA=1 GROUPB=2-50 MEAN LABEL=d1
MFILTER_BETWEEN DATA=d1 LOWER=0 UPPER=3.0 SMEAR=0.0001 MEAN LABEL=d4
Generated by Doxygen
254
Collective Variables
More complicated things can be done by using the label of a filter as input to a new multicolvar as shown in
the example below. Here the coordination numbers of all atoms are computed. The atoms with a coordination
number between 4 and 6 are then identified using the filter. This reduced list of atoms is then used as input to a
second coordination number calculation. This second coordination number thus measures the number of atoms 4-6
coordinated atoms each of the 4-6 coordination atoms is bound to.
BEGIN_PLUMED_FILE
c1: COORDINATIONNUMBER SPECIES=1-150 SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0}
cf: MFILTER_BETWEEN DATA=c1 LOWER=4 UPPER=6 SMEAR=0.5 LOWMEM
c2: COORDINATIONNUMBER SPECIES=cf SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0} MORE_THAN={RATIONAL D_0=2.0 R_0=0.1}
5.5.37
MFILTER_LESS
This is part of the multicolvar module
This action can be used to filter the distribution of colvar values in a MultiColvar so that one can compute the mean
and so on for only those multicolvars less than a tolerance.
This action can be used to create a dynamic group of atom based on the value of a multicolvar. In this action a
multicolvar is within the dynamic group if its value is less than a target. In actuality a weight, wi is ascribed to each
colvar, si calculated by a multicolvar and this weight measures the degree to which a colvar is a member of the
group. This weight is a number between 0 and 1 that is calculated using a switchingfunction , σ . If one calculates a
function of the set of multicolvars these weights are included in the calculation. As such if one calculates the MEAN,
µ of a filtered multicolvar what is computed is the following:
P
wi si
µ = Pi
i wi
One is thus calculating the mean for those colvars that are less than the target.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Generated by Doxygen
5.5 MultiColvar
255
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere in
the input file by using the label.vmean
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function
D_0
( default=0.0 ) The d_0 parameter of the switching function
R_0
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
Generated by Doxygen
256
Collective Variables
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MIN
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
MAX
is calculated using
ALT_MIN
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make this quantity continuous the minimum
P
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
Examples
The example shown below calculates the mean for those distances that less than 1.5 nm in length
BEGIN_PLUMED_FILE
DISTANCES GROUPA=1 GROUPB=2-50 MEAN LABEL=d1
MFILTER_LESS DATA=d1 SWITCH={GAUSSIAN D_0=1.5 R_0=0.00001} MEAN LABEL=d4
5.5.38
MFILTER_MORE
This is part of the multicolvar module
Generated by Doxygen
5.5 MultiColvar
257
This action can be used to filter the distribution of colvar values in a MultiColvar so that one can compute the mean
and so on for only those multicolvars more than a tolerance.
This action can be used to create a dynamic group of atom based on the value of a multicolvar. In this action a
multicolvar is within the dynamic group if its value is greater than a target. In actuality a weight, wi is ascribed to
each colvar, si calculated by a multicolvar and this weight measures the degree to which a colvar is a member of
the group. This weight is calculated using a switchingfunction , σ so it is given by:
wi = 1 − σ(si )
If one calculates a function of the set of multicolvars these weights are included in the calculation. As such if one
calculates the MEAN, µ of a filtered multicolvar what is computed is the following:
P
wi si
µ = Pi
i wi
One is thus calculating the mean for those colvars that are greater than the target.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere in
the input file by using the label.vmean
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
Generated by Doxygen
258
Collective Variables
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D_0
( default=0.0 ) The d_0 parameter of the switching function
R_0
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MOMENTS
calculate the moments of the distribution of collective variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MIN
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
MAX
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
is calculated using
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
Generated by Doxygen
5.5 MultiColvar
259
ALT_MIN
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
min
Examples
The example shown below calculates the mean for those distances that greater than 1.5 nm in length
BEGIN_PLUMED_FILE
DISTANCES GROUPA=1 GROUPB=2-50 MEAN LABEL=d1
MFILTER_MORE DATA=d1 SWITCH={GAUSSIAN D_0=1.5 R_0=0.00001} MEAN LABEL=d4
More complicated things can be done by using the label of a filter as input to a new multicolvar as shown in the
example below. Here the coordination numbers of all atoms are computed. The atoms with a coordination number
greater than 2 are then identified using the filter. This reduced list of atoms is then used as input to a second
coordination number calculation. This second coordination number thus measures the number of two-coordinated
atoms that each of the two-coordinated atoms is bound to.
BEGIN_PLUMED_FILE
1: COORDINATIONNUMBER SPECIES=1-150 SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0}
cf: MFILTER_MORE DATA=c1 SWITCH={RATIONAL D_0=2.0 R_0=0.1} LOWMEM
c2: COORDINATIONNUMBER SPECIES=cf SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0} MORE_THAN={RATIONAL D_0=2.0 R_0=0.1}
5.5.39
AROUND
This is part of the multicolvar module
This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a
particular, user-specified part of of the cell.
Each of the base quantities calculated by a multicolvar can can be assigned to a particular point in three dimensional
space. For example, if we have the coordination numbers for all the atoms in the system each coordination number
can be assumed to lie on the position of the central atom. Because each base quantity can be assigned to a
particular point in space we can calculate functions of the distribution of base quantities in a particular part of the
box by using:
P
sτ =
f (si )w(xi , yi , zi )
iP
i
Generated by Doxygen
w(xi , yi , zi )
260
Collective Variables
where the sum is over the collective variables, si , each of which can be thought to be at (xi , yi , zi ). The function
w(xi , yi , zi ) measures whether or not the system is in the subregion of interest. It is equal to:
Z
xu
Z
yu
Z
zu
w(xi , yi , zi ) =
xl
yl
zl
dxdydzK
x − xi
σ
K
y − yi
σ
K
z − zi
σ
where K is one of the kernel functions described on histogrambead and σ is a bandwidth parameter. The function
(si ) can be any of the usual LESS_THAN, MORE_THAN, WITHIN etc that are used in all other multicolvars.
When AROUND is used with the DENSITY action the number of atoms in the specified region is calculated
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The atoms involved can be specified using
ATOM
the atom whose vicinity we are interested in examining. For more information on how to specify lists of
atoms see Groups and Virtual Atoms
Generated by Doxygen
5.5 MultiColvar
261
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
SIGMA
the width of the function to be used for kernel density estimation
KERNEL
( default=gaussian ) the type of kernel function to be used
XLOWER
( default=0.0 ) the lower boundary in x relative to the x coordinate of the atom (0 indicates use full
extent of box).
XUPPER
( default=0.0 ) the upper boundary in x relative to the x coordinate of the atom (0 indicates use full
extent of box).
YLOWER
( default=0.0 ) the lower boundary in y relative to the y coordinate of the atom (0 indicates use full
extent of box).
YUPPER
( default=0.0 ) the upper boundary in y relative to the y coordinate of the atom (0 indicates use full
extent of box).
ZLOWER
( default=0.0 ) the lower boundary in z relative to the z coordinate of the atom (0 indicates use full
extent of box).
ZUPPER
( default=0.0 ) the upper boundary in z relative to the z coordinate of the atom (0 indicates use full
extent of box).
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) calculate quantities for colvars that are on atoms outside the
region of interest
OUTSIDE
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number of variables more than a certain target value. This quanP
tity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
MORE_THAN
Generated by Doxygen
262
Collective Variables
BETWEEN
HISTOGRAM
SUM
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
Examples
The following commands tell plumed to calculate the average coordination number for the atoms that have x (in
fractional coordinates) within 2.0 nm of the com of mass c1. The final value will be labeled s.mean.
BEGIN_PLUMED_FILE
COM ATOMS=1-100 LABEL=c1
COORDINATIONNUMBER SPECIES=1-100 R_0=1.0 LABEL=c
AROUND DATA=c ORIGIN=c1 XLOWER=-2.0 XUPPER=2.0 SIGMA=0.1 MEAN LABEL=s
5.5.40
CAVITY
This is part of the multicolvar module
This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a
box defined by the positions of four atoms.
Each of the base quantities calculated by a multicolvar can can be assigned to a particular point in three dimensional
space. For example, if we have the coordination numbers for all the atoms in the system each coordination number
can be assumed to lie on the position of the central atom. Because each base quantity can be assigned to a
particular point in space we can calculate functions of the distribution of base quantities in a particular part of the
box by using:
P
sτ =
f (si )w(ui , vi , wi )
iP
i
w(ui , vi , wi )
where the sum is over the collective variables, si , each of which can be thought to be at (ui , vi , zi ). The function
(si ) can be any of the usual LESS_THAN, MORE_THAN, WITHIN etc that are used in all other multicolvars. Notice
that here (at variance with what is done in AROUND) we have transformed from the usual (xi , yi , zi ) position to a
position in (ui , vi , zi ). This is done using a rotation matrix as follows:
( u i vi wi ) = R ( x i − xo yi − yo zi − zo )
Generated by Doxygen
5.5 MultiColvar
263
where R is a rotation matrix that is calculated by constructing a set of three orthonormal vectors from the reference
positions specified by the user. The first of these unit vectors points from the first reference atom to the second. The
second is then the normal to the plane containing atoms 1,2 and 3 and the the third is the unit vector orthogonal to
these first two vectors. (xo , yo , zo ), meanwhile, specifies the position of the first reference atom.
In the previous function w(ui , vi , wi ) measures whether or not the system is in the subregion of interest. It is equal
to:
Z
u0
Z
v0
Z
w0
w(ui , vi , wi ) =
0
0
0
dudvdwK
u − ui
σ
K
v − vi
σ
K
w − wi
σ
where K is one of the kernel functions described on histogrambead and σ is a bandwidth parameter. The vector
connecting atom 1 to atom 4 is used to define the extent of the box in each of the u, v and w directions. Essentially
the vector connecting atom 1 to atom 4 is projected onto the three unit vectors described above and the resulting
projections determine the u0 , v 0 and w0 parameters in the above expression.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The atoms involved can be specified using
Generated by Doxygen
264
Collective Variables
ATOMS
the positions of four atoms that define spatial extent of the cavity. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
SIGMA
the width of the function to be used for kernel density estimation
KERNEL
( default=gaussian ) the type of kernel function to be used
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) calculate quantities for colvars that are on atoms outside the
region of interest
OUTSIDE
PRINT_BOX
( default=off ) write out the positions of the corners of the box to an xyz file
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
MORE_THAN
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
Generated by Doxygen
5.5 MultiColvar
265
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
SUM
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
FILE
UNITS
the file on which to write out the box coordinates
( default=nm ) the units in which to write out the corners of the box
Examples
The following commands tell plumed to calculate the number of atoms in an ion channel in a protein. The extent of
the channel is calculated from the positions of atoms 1, 4, 5 and 11. The final value will be labeled cav.
BEGIN_PLUMED_FILE
d1: DENSITY SPECIES=20-500
CAVITY DATA=d1 ATOMS=1,4,5,11 SIGMA=0.1 LABEL=cav
The following command tells plumed to calculate the coordination numbers (with other water molecules) for the
water molecules in the protein channel described above. The average coordination number and the number of
coordination numbers more than 4 is then calculated. The values of these two quantities are given the labels
cav.mean and cav.morethan
BEGIN_PLUMED_FILE
d1: COORDINATIONNUMBER SPECIES=20-500
CAVITY DATA=d1 ATOMS=1,4,5,11 SIGMA=0.1 MEAN MORE_THAN={RATIONAL R_0=4} LABEL=cav
5.5.41
INCYLINDER
This is part of the multicolvar module
This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a
particular, user-specified part of of the cell.
Each of the base quantities calculated by a multicolvar can can be assigned to a particular point in three dimensional
space. For example, if we have the coordination numbers for all the atoms in the system each coordination number
can be assumed to lie on the position of the central atom. Because each base quantity can be assigned to a
particular point in space we can calculate functions of the distribution of base quantities in a particular part of the
box by using:
P
sτ =
f (si )σ(rxy )
iP
i
σ(rxy )
where the sum is over the collective variables, si , each of which can be thought to be at (xi , yi , zi ). The function σ
is a switchingfunction that acts on the distance between the point at which the collective is located (xi , yi , zi ) and
Generated by Doxygen
266
Collective Variables
the position of the atom that was specified using the ORIGIN keyword projected in the xy plane if DIRECTION=z is
used. In other words:
rxy = sqrt(xi − x0 )2 + (yi − y0 )2
In short this function, σ(rxy ), measures whether or not the CV is within a cylinder that runs along the axis specified
using the DIRECTION keyword and that is centered on the position of the atom specified using ORIGIN.
The function (si ) can be any of the usual LESS_THAN, MORE_THAN, WITHIN etc that are used in all other
multicolvars.
When INCYLINDER is used with the DENSITY action the number of atoms in the specified region is calculated
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The atoms involved can be specified using
ATOM
the atom whose vicinity we are interested in examining. For more information on how to specify lists of
atoms see Groups and Virtual Atoms
Compulsory keywords
Generated by Doxygen
5.5 MultiColvar
267
DATA
The multicolvar that calculates the set of base quantities that we are interested in
KERNEL
( default=gaussian ) the type of kernel function to be used
DIRECTION
the direction of the long axis of the cylinder. Must be x, y or z
RADIUS
a switching function that gives the extent of the cylinder in the plane perpendicular to the direction
LOWER
( default=0.0 ) the lower boundary on the direction parallel to the long axis of the cylinder
UPPER
( default=0.0 ) the upper boundary on the direction parallel to the long axis of the cylinder
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) calculate quantities for colvars that are on atoms outside the
region of interest
OUTSIDE
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
MORE_THAN
BETWEEN
HISTOGRAM
Generated by Doxygen
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
268
Collective Variables
SUM
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
SIGMA
the width of the function to be used for kernel density estimation
Examples
The input below can be use to calculate the average coordination numbers for those atoms that are within a cylindrical tube of radius 1.5 nm that is centered on the position of atom 101 and that has its long axis parallel to the
z-axis.
BEGIN_PLUMED_FILE
c1: COORDINATIONNUMBER SPECIES=1-100 SWITCH={RATIONAL R_0=0.1}
d2: INCYLINDER ATOM=101 DATA=d1 DIRECTION=Z RADIUS={TANH R_0=1.5} SIGMA=0.1 LOWER=-0.1 UPPER=0.1 MEAN
PRINT ARG=d2.* FILE=colvar
5.5.42
INENVELOPE
This is part of the multicolvar module
This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a
region where the density of a certain type of atom is high.
This collective variable can be used to determine whether colvars are within region where the density of a particular
atom is high. This is achieved by calculating the following function at the point where the atom is located (x, y, z):
"
wj = 1 − σ
N
X
i=1
K
x − xi y − yi z − zi
,
,
σx
σy
σz
#
Here σ is a switchingfunction and K is a kernelfunctions. The sum runs over the atoms specified using the ATOMS
keyword and a wj value is calculated for each of the central atoms of the input multicolvar.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Generated by Doxygen
5.5 MultiColvar
269
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The atoms involved can be specified using
ATOMS
the atom whose positions we are constructing a field from. For more information on how to specify
lists of atoms see Groups and Virtual Atoms
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
KERNEL
( default=gaussian ) the type of kernel function to be used
BANDWIDTH
the bandwidths for kernel density estimation
CONTOUR
a switching function that tells PLUMED how large the density should be
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) calculate quantities for colvars that are on atoms outside the
region of interest
OUTSIDE
VMEAN
Generated by Doxygen
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
270
Collective Variables
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
LESS_THAN
calculate the number of variables less than a certain target value. This quanP
tity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
MORE_THAN
BETWEEN
HISTOGRAM
SUM
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
Examples
The input below calculates a density field from the positions of atoms 1-14400. The number of the atoms that are
specified in the DENSITY action that are within a region where the density field is greater than 2.0 is then calculated.
BEGIN_PLUMED_FILE
d1: DENSITY SPECIES=14401-74134:3 LOWMEM
fi: INENVELOPE DATA=d1 ATOMS=1-14400 CONTOUR={RATIONAL D_0=2.0 R_0=1.0} BANDWIDTH=0.1,0.1,0.1 LOWMEM
PRINT ARG=fi,rr.* FILE=colvar
5.5.43
INSPHERE
This is part of the multicolvar module
This quantity can be used to calculate functions of the distribution of collective variables for the atoms that lie in a
particular, user-specified part of of the cell.
Each of the base quantities calculated by a multicolvar can can be assigned to a particular point in three dimensional
space. For example, if we have the coordination numbers for all the atoms in the system each coordination number
Generated by Doxygen
5.5 MultiColvar
271
can be assumed to lie on the position of the central atom. Because each base quantity can be assigned to a
particular point in space we can calculate functions of the distribution of base quantities in a particular part of the
box by using:
P
sτ =
f (si )σ(r)
iP
i
σ(r)
where the sum is over the collective variables, si , each of which can be thought to be at (xi , yi , zi ). The function σ
is a switchingfunction that acts on the distance between the point at which the collective is located (xi , yi , zi ) and
the position of the atom that was specified using the ORIGIN keyword. In other words:
r = sqrt(xi − x0 )2 + (yi − y0 )2 + (zi − z0 )2
In short this function, σ(rxy ), measures whether or not the CV is within a sphere that is centered on the position of
the atom specified using the keyword ORIGIN.
The function (si ) can be any of the usual LESS_THAN, MORE_THAN, WITHIN etc that are used in all other
multicolvars.
When INCYLINDER is used with the DENSITY action the number of atoms in the specified region is calculated
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
Generated by Doxygen
272
Collective Variables
The atoms involved can be specified using
ATOM
the atom whose vicinity we are interested in examining. For more information on how to specify lists of
atoms see Groups and Virtual Atoms
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
KERNEL
( default=gaussian ) the type of kernel function to be used
RADIUS
the switching function that tells us the extent of the spherical region of interest
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) calculate quantities for colvars that are on atoms outside the
region of interest
OUTSIDE
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
MORE_THAN
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
Generated by Doxygen
5.5 MultiColvar
273
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
SUM
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
Examples
The input below can be use to calculate the average coordination numbers for those atoms that are within a sphere
of radius 1.5 nm that is centered on the position of atom 101.
BEGIN_PLUMED_FILE
c1: COORDINATIONNUMBER SPECIES=1-100 SWITCH={RATIONAL R_0=0.1}
d2: INSPHERE ATOM=101 DATA=d1 RADIUS={TANH R_0=1.5} SIGMA=0.1 LOWER=-0.1 UPPER=0.1 MEAN
PRINT ARG=d2.* FILE=colvar
5.5.44
TETRAHEDRALPORE
This is part of the multicolvar module
This quantity can be used to calculate functions of the distribution of collective variables for the atoms lie that lie in
a box defined by the positions of four atoms at the corners of a tetrahedron.
Each of the base quantities calculated by a multicolvar can can be assigned to a particular point in three dimensional
space. For example, if we have the coordination numbers for all the atoms in the system each coordination number
can be assumed to lie on the position of the central atom. Because each base quantity can be assigned to a
particular point in space we can calculate functions of the distribution of base quantities in a particular part of the
box by using:
P
sτ =
f (si )w(ui , vi , wi )
iP
i
w(ui , vi , wi )
where the sum is over the collective variables, si , each of which can be thought to be at (ui , vi , zi ). The function
(si ) can be any of the usual LESS_THAN, MORE_THAN, WITHIN etc that are used in all other multicolvars. Notice
that here (at variance with what is done in AROUND) we have transformed from the usual (xi , yi , zi ) position to a
position in (ui , vi , zi ). This is done using a rotation matrix as follows:
( u i vi wi ) = R ( x i − xo yi − yo zi − zo )
where R is a rotation matrix that is calculated by constructing a set of three orthonormal vectors from the reference
positions specified by the user. Initially unit vectors are found by calculating the bisector, b, and cross product, c,
of the vectors connecting atoms 1 and 2. A third unit vector, p is then found by taking the cross product between
Generated by Doxygen
274
Collective Variables
the cross product calculated during the first step, c and the bisector, b. From this second cross product p and the
bisector b two new vectors are calculated using:
v1 = cos
π
4
π
b + sin
4
p
and
v2 = cos
π
4
b − sin
π
4
p
In the previous function w(ui , vi , wi ) measures whether or not the system is in the subregion of interest. It is equal
to:
Z
u0
Z
v0
Z
w0
w(ui , vi , wi ) =
0
0
0
dudvdwK
u − ui
σ
K
v − vi
σ
K
w − wi
σ
where K is one of the kernel functions described on histogrambead and σ is a bandwidth parameter. The values of
u0 and v 0 are found by finding the projections of the vectors connecting atoms 1 and 2 and 1 and 3 v1 and v2 . This
gives four projections: the largest two projections are used in the remainder of the calculations. w0 is calculated by
taking the projection of the vector connecting atoms 1 and 4 on the vector c. Notice that the manner by which this
box is constructed differs from the way this is done in CAVITY. This is in fact the only point of difference between
these two actions.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
Generated by Doxygen
5.5 MultiColvar
275
The atoms involved can be specified using
ATOMS
the positions of four atoms that define spatial extent of the cavity. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
SIGMA
the width of the function to be used for kernel density estimation
KERNEL
( default=gaussian ) the type of kernel function to be used
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) calculate quantities for colvars that are on atoms outside the
region of interest
OUTSIDE
PRINT_BOX
( default=off ) write out the positions of the corners of the box to an xyz file
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
MORE_THAN
BETWEEN
Generated by Doxygen
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
276
Collective Variables
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
SUM
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
FILE
UNITS
the file on which to write out the box coordinates
( default=nm ) the units in which to write out the corners of the box
Examples
The following commands tell plumed to calculate the number of atom inside a tetrahedral cavity. The extent of the
tetrahedral cavity is calculated from the positions of atoms 1, 4, 5, and 11, The final value will be labeled cav.
BEGIN_PLUMED_FILE
d1: DENSITY SPECIES=20-500
TETRAHEDRALPORE DATA=d1 ATOMS=1,4,5,11 SIGMA=0.1 LABEL=cav
The following command tells plumed to calculate the coordination numbers (with other water molecules) for the
water molecules in the tetrahedral cavity described above. The average coordination number and the number of
coordination numbers more than 4 is then calculated. The values of these two quantities are given the labels
cav.mean and cav.morethan
BEGIN_PLUMED_FILE
d1: COORDINATIONNUMBER SPECIES=20-500
CAVITY DATA=d1 ATOMS=1,4,5,11 SIGMA=0.1 MEAN MORE_THAN={RATIONAL R_0=4} LABEL=cav
5.5.45
GRADIENT
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate the gradient of the average value of a multicolvar value
This command allows you to calculate the collective variable discussed in [29].
The atoms involved can be specified using
ORIGIN
we will use the position of this atom as the origin in our calculation. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Generated by Doxygen
5.5 MultiColvar
277
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
DIR
( default=xyz ) the directions in which we are calculating the gradient. Should be x, y, z, xy, xz, yz or
xyz
NBINS
number of bins to use in each direction for the calculation of the gradient
SIGMA
( default=1.0 ) the width of the function to be used for kernel density estimation
KERNEL
( default=gaussian ) the type of kernel function to be used
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Examples
The input below calculates the gradient of the density of atoms in the manner described in [29] in order to detect
whether or not atoms are distributed uniformly along the x-axis of the simulation cell.
BEGIN_PLUMED_FILE
d1: DENSITY SPECIES=1-50
s1: GRADIENT ORIGIN=1 DATA=d1 DIR=x NBINS=4 SIGMA=1.0
PRINT ARG=s1 FILE=colvar
The input below calculates the coordination numbers of the 50 atoms in the simulation cell. The gradient of this
quantity is then evaluated in the manner described using the equation above to detect whether the average values
of the coordination number are uniformly distributed along the x-axis of the simulation cell.
BEGIN_PLUMED_FILE
d2: COORDINATIONNUMBER SPECIES=1-50 SWITCH={RATIONAL R_0=2.0} MORE_THAN={EXP R_0=4.0}
s2: GRADIENT ORIGIN=1 DATA=d2 DIR=x NBINS=4 SIGMA=1.0
PRINT ARG=s2 FILE=colvar
5.5.46
INTERMOLECULARTORSIONS
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Generated by Doxygen
278
Collective Variables
Calculate torsion angles between vectors on adjacent molecules
This variable can be used to calculate the average torsional angles between vectors. In other words, it can be used
to compute quantities like this:
P
i6=j
s= P
σ(rij )θij
i6=j
σ(rij )
Here the sums run over all pairs of molecules. σ(rij ) is a switchingfunction that action on the distance between
the centers of molecules i and j . θij is then the torsional angle between an orientation vector for molecule i and
molecule j .
This command can be used to calculate the intermolecular torsional angles between the orientations of nearby
molecules. The orientation of a molecule can be calculated by using either the MOLECULES or the PLANES
commands. These two commands calculate the orientation of a bond in the molecule or the orientation of a plane
containing three of the molecule's atoms. Furthermore, when we use these commands we think of molecules as
objects that lie at a point in space and that have an orientation. This command calculates the torsional angles
between the orientations of these objects. We can then calculates functions of a large number of these torsional
angles that measures things such as the number of torsional angles that are within a particular range. Because it
is often useful to only consider the torsional angles between objects that are within a certain distance of each other
we can, when calculating these sums, perform a weighted sum and use a switchingfunction to ensure that we focus
on molecules that are close together.
The atoms involved can be specified using
MOLS
The molecules you would like to calculate the torsional angles between. This should be the label/s
of MOLECULES or PLANES actions. For more information on how to specify lists of atoms see
Groups and Virtual Atoms
Or alternatively by using
MOLSA
MOLSB
In this version of the input the torsional angles between all pairs of atoms including one atom from
MOLSA one atom from MOLSB will be computed. This should be the label/s of MOLECULES or
PLANES actions
In this version of the input the torsional angles between all pairs of atoms including one atom from
MOLSA one atom from MOLSB will be computed. This should be the label/s of MOLECULES or
PLANES actions
Compulsory keywords
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Generated by Doxygen
5.5 MultiColvar
279
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
SERIAL
TIMINGS
LOWMEM
SWITCH
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) lower the memory requirements
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
Examples
The example input below is necessarily but gives you an idea of what can be achieved using this action. The
orientations and positions of four molecules are defined using the MOLECULES action as the position of the
centers of mass of the two atoms specified and the direction of the vector connecting the two atoms that were
specified. The torsional angles between the molecules are then calculated by the INTERMOLECULARTORSIONS
command labelled torsion_p. We then compute a HISTOGRAM that shows the distribution that these torsional angles take in the structure. The weight a given torsional angle contributes to this HISTOGRAM is determined using
a switchingfunction that acts on the distance between the two molecules. As such the torsional angles between
molecules that are close together contribute a high weight to the histogram while the torsional angles between
molecules that are far apart does not contribute to the histogram. The histogram is averaged over the whole trajectory and output once all the trajectory frames have been read.
BEGIN_PLUMED_FILE
m1: MOLECULES MOL1=1,2 MOL2=3,4 MOL3=5,6 MOL4=7,8
torsion_p: INTERMOLECULARTORSIONS MOLS=m1 SWITCH={RATIONAL R_0=0.25 D_0=2.0 D_MAX=3.0}
htt_p: HISTOGRAM DATA=torsion_p GRID_MIN=-pi GRID_MAX=pi BANDWIDTH=0.1 GRID_BIN=200 STRIDE=1
DUMPGRID GRID=htt_p FILE=myhist.out
5.5.47
LOCAL_AVERAGE
This is part of the multicolvar module
Calculate averages over spherical regions centered on atoms
As is explained in this video certain multicolvars calculate one scalar quantity or one vector for each of the
atoms in the system. For example COORDINATIONNUMBER measures the coordination number of each of the
atoms in the system and Q4 measures the fourth order Steinhardt parameter for each of the atoms in the system.
These quantities provide tell us something about the disposition of the atoms in the first coordination sphere of each
of the atoms of interest. Lechner and Dellago [23] have suggested that one can probe local order in a system by
taking the average value of such symmetry functions over the atoms within a spherical cutoff of each of these atoms
in the systems. When this is done with Steinhardt parameters they claim this gives a coordinate that is better able
to distinguish solid and liquid configurations of Lennard-Jones atoms.
You can calculate such locally averaged quantities within plumed by using the LOCAL_AVERAGE command. This
command calculates the following atom-centered quantities:
Generated by Doxygen
280
Collective Variables
si =
ci +
P
1+
Pj
σ(rij )cj
j
σ(rij )
where the ci and cj values can be for any one of the symmetry functions that can be calculated using plumed
multicolvars. The function σ(rij ) is a switchingfunction that acts on the distance between atoms i and j . Lechner
and Dellago suggest that the parameters of this function should be set so that it the function is equal to one when
atom j is in the first coordination sphere of atom i and is zero otherwise.
The si quantities calculated using the above command can be again thought of as atom-centered symmetry functions. They thus operate much like multicolvars. You can thus calculate properties of the distribution of si values
using MEAN, LESS_THAN, HISTOGRAM and so on. You can also probe the value of these averaged variables in
regions of the box by using the command in tandem with the AROUND command.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
Generated by Doxygen
5.5 MultiColvar
SPECIES
281
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Or alternatively by using
SPECIESA
SPECIESB
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
SERIAL
TIMINGS
LOWMEM
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) lower the memory requirements
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
Generated by Doxygen
282
Collective Variables
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
BETWEEN
HISTOGRAM
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
VSUM
calculate the norm of the sum of vectors. The final value can be referenced
using label.vsum. You can use multiple instances of this keyword i.e. VSU←M1, VSUM2, VSUM3... The corresponding values are then referenced using
label.vsum-1, label.vsum-2, label.vsum-3...
Examples
This example input calculates the coordination numbers for all the atoms in the system. These coordination numbers
are then averaged over spherical regions. The number of averaged coordination numbers that are greater than 4 is
then output to a file.
BEGIN_PLUMED_FILE
COORDINATIONNUMBER SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=d1
LOCAL_AVERAGE ARG=d1 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MORE_THAN={RATIONAL R_0=4} LABEL=la
PRINT ARG=la.* FILE=colvar
Generated by Doxygen
5.5 MultiColvar
283
This example input calculates the q4 (see Q4) vectors for each of the atoms in the system. These vectors are then
averaged component by component over a spherical region. The average value for this quantity is then output to a
file. This calculates the quantities that were used in the paper by Lechner and Dellago [23]
BEGIN_PLUMED_FILE
Q4 SPECIES=1-64 SWITCH={RATIONAL D_0=1.3 R_0=0.2} LABEL=q4
LOCAL_AVERAGE ARG=q4 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LABEL=la
PRINT ARG=la.* FILE=colvar
5.5.48
LOCAL_Q3
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate the local degree of order around an atoms by taking the average dot product between the q3 vector on
the central atom and the q3 vector on the atoms in the first coordination sphere.
The Q3 command allows one to calculate one complex vectors for each of the atoms in your system that describe
the degree of order in the coordination sphere around a particular atom. The difficulty with these vectors comes
when combining the order parameters from all of the individual atoms/molecules so as to get a measure of the
global degree of order for the system. The simplest way of doing this - calculating the average Steinhardt parameter
- can be problematic. If one is examining nucleation say only the order parameters for those atoms in the nucleus
will change significantly when the nucleus forms. The order parameters for the atoms in the surrounding liquid
will remain pretty much the same. As such if one models a small nucleus embedded in a very large amount of
solution/melt any change in the average order parameter will be negligible. Substantial changes in the value of this
average can be observed in simulations of nucleation but only because the number of atoms is relatively small.
When the average Q3 parameter is used to bias the dynamics a problems can occur. These averaged coordinates
cannot distinguish between the correct, single-nucleus pathway and a concerted pathway in which all the atoms
rearrange themselves into their solid-like configuration simultaneously. This second type of pathway would be
impossible in reality because there is a large entropic barrier that prevents concerted processes like this from
happening. However, in the finite sized systems that are commonly simulated this barrier is reduced substantially.
As a result in simulations where average Steinhardt parameters are biased there are often quite dramatic system
size effects
If one wants to simulate nucleation using some form on biased dynamics what is really required is an order parameter that measures:
• Whether or not the coordination spheres around atoms are ordered
• Whether or not the atoms that are ordered are clustered together in a crystalline nucleus
LOCAL_AVERAGE and NLINKS are variables that can be combined with the Steinhardt parameters allow to calculate variables that satisfy these requirements. LOCAL_Q3 is another variable that can be used in these sorts of
calculations. The LOCAL_Q3 parameter for a particular atom is a number that measures the extent to which the
orientation of the atoms in the first coordination sphere of an atom match the orientation of the central atom. It does
this by calculating the following quantity for each of the atoms in the system:
P
si =
Generated by Doxygen
j
σ(rij )
P3
∗
q3m
(i)q3m (j)
Pm=−3
σ(r
)
ij
j
284
Collective Variables
where q3m (i) and q3m (j) are the 3rd order Steinhardt vectors calculated for atom i and atom j respectively and the
asterisk denotes complex conjugation. The function σ(rij ) is a switchingfunction that acts on the distance between
atoms i and j . The parameters of this function should be set so that it the function is equal to one when atom j is
in the first coordination sphere of atom i and is zero otherwise. The sum in the numerator of this expression is the
dot product of the Steinhardt parameters for atoms i and j and thus measures the degree to which the orientations
of these adjacent atoms is correlated.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Generated by Doxygen
5.5 MultiColvar
285
Or alternatively by using
SPECIESA
SPECIESB
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
Generated by Doxygen
286
MIN
BETWEEN
HISTOGRAM
Collective Variables
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
(s
ment of a distribution is calculated using N
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Examples
The following command calculates the average value of the LOCAL_Q3 parameter for the 64 Lennard Jones atoms
in the system under study and prints this quantity to a file called colvar.
BEGIN_PLUMED_FILE
Q3 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q3
LOCAL_Q3 SPECIES=q3 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LABEL=lq3
PRINT ARG=lq3.mean FILE=colvar
The following input calculates the distribution of LOCAL_Q3 parameters at any given time and outputs this information to a file.
BEGIN_PLUMED_FILE
Q3 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q3
LOCAL_Q3 SPECIES=q3 SWITCH={RATIONAL D_0=1.3 R_0=0.2} HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0
PRINT ARG=lq3.* FILE=colvar
The following calculates the LOCAL_Q3 parameters for atoms 1-5 only. For each of these atoms comparisons of
the geometry of the coordination sphere are done with those of all the other atoms in the system. The final quantity
is the average and is outputted to a file
Generated by Doxygen
5.5 MultiColvar
287
BEGIN_PLUMED_FILE
Q3 SPECIESA=1-5 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q3a
Q3 SPECIESA=6-64 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q3b
LOCAL_Q3 SPECIES=q3a,q3b SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LOWMEM LABEL=w3
PRINT ARG=w3.* FILE=colvar
5.5.49
LOCAL_Q4
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate the local degree of order around an atoms by taking the average dot product between the q4 vector on
the central atom and the q4 vector on the atoms in the first coordination sphere.
The Q4 command allows one to calculate one complex vectors for each of the atoms in your system that describe
the degree of order in the coordination sphere around a particular atom. The difficulty with these vectors comes
when combining the order parameters from all of the individual atoms/molecules so as to get a measure of the
global degree of order for the system. The simplest way of doing this - calculating the average Steinhardt parameter
- can be problematic. If one is examining nucleation say only the order parameters for those atoms in the nucleus
will change significantly when the nucleus forms. The order parameters for the atoms in the surrounding liquid
will remain pretty much the same. As such if one models a small nucleus embedded in a very large amount of
solution/melt any change in the average order parameter will be negligible. Substantial changes in the value of this
average can be observed in simulations of nucleation but only because the number of atoms is relatively small.
When the average Q4 parameter is used to bias the dynamics a problems can occur. These averaged coordinates
cannot distinguish between the correct, single-nucleus pathway and a concerted pathway in which all the atoms
rearrange themselves into their solid-like configuration simultaneously. This second type of pathway would be
impossible in reality because there is a large entropic barrier that prevents concerted processes like this from
happening. However, in the finite sized systems that are commonly simulated this barrier is reduced substantially.
As a result in simulations where average Steinhardt parameters are biased there are often quite dramatic system
size effects
If one wants to simulate nucleation using some form on biased dynamics what is really required is an order parameter that measures:
• Whether or not the coordination spheres around atoms are ordered
• Whether or not the atoms that are ordered are clustered together in a crystalline nucleus
LOCAL_AVERAGE and NLINKS are variables that can be combined with the Steinhardt parameters allow to calculate variables that satisfy these requirements. LOCAL_Q4 is another variable that can be used in these sorts of
calculations. The LOCAL_Q4 parameter for a particular atom is a number that measures the extent to which the
orientation of the atoms in the first coordination sphere of an atom match the orientation of the central atom. It does
this by calculating the following quantity for each of the atoms in the system:
P
si =
j
σ(rij )
P4
∗
(i)q4m (j)
q4m
Pm=−4
σ(r
)
ij
j
where q4m (i) and q4m (j) are the fourth order Steinhardt vectors calculated for atom i and atom j respectively
and the asterisk denotes complex conjugation. The function σ(rij ) is a switchingfunction that acts on the distance
between atoms i and j . The parameters of this function should be set so that it the function is equal to one
when atom j is in the first coordination sphere of atom i and is zero otherwise. The sum in the numerator of this
expression is the dot product of the Steinhardt parameters for atoms i and j and thus measures the degree to which
the orientations of these adjacent atoms is correlated.
Generated by Doxygen
288
Collective Variables
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Or alternatively by using
Generated by Doxygen
5.5 MultiColvar
SPECIESA
SPECIESB
289
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
Generated by Doxygen
290
MIN
BETWEEN
HISTOGRAM
Collective Variables
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
(s
− s)m , where s is the
ment of a distribution is calculated using N
i
i=1
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Examples
The following command calculates the average value of the LOCAL_Q4 parameter for the 64 Lennard Jones atoms
in the system under study and prints this quantity to a file called colvar.
BEGIN_PLUMED_FILE
Q4 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q4
LOCAL_Q4 SPECIES=q4 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LABEL=lq4
PRINT ARG=lq4.mean FILE=colvar
The following input calculates the distribution of LOCAL_Q4 parameters at any given time and outputs this information to a file.
BEGIN_PLUMED_FILE
Q4 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q4
LOCAL_Q4 SPECIES=q4 SWITCH={RATIONAL D_0=1.3 R_0=0.2} HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0
PRINT ARG=lq4.* FILE=colvar
The following calculates the LOCAL_Q4 parameters for atoms 1-5 only. For each of these atoms comparisons of
the geometry of the coordination sphere are done with those of all the other atoms in the system. The final quantity
is the average and is outputted to a file
Generated by Doxygen
5.5 MultiColvar
291
BEGIN_PLUMED_FILE
Q4 SPECIESA=1-5 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q4a
Q4 SPECIESA=6-64 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q4b
LOCAL_Q4 SPECIES=q4a,q4b SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LOWMEM LABEL=w4
PRINT ARG=w4.* FILE=colvar
5.5.50
LOCAL_Q6
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate the local degree of order around an atoms by taking the average dot product between the q6 vector on
the central atom and the q6 vector on the atoms in the first coordination sphere.
The Q6 command allows one to calculate one complex vectors for each of the atoms in your system that describe
the degree of order in the coordination sphere around a particular atom. The difficulty with these vectors comes
when combining the order parameters from all of the individual atoms/molecules so as to get a measure of the
global degree of order for the system. The simplest way of doing this - calculating the average Steinhardt parameter
- can be problematic. If one is examining nucleation say only the order parameters for those atoms in the nucleus
will change significantly when the nucleus forms. The order parameters for the atoms in the surrounding liquid
will remain pretty much the same. As such if one models a small nucleus embedded in a very large amount of
solution/melt any change in the average order parameter will be negligible. Substantial changes in the value of this
average can be observed in simulations of nucleation but only because the number of atoms is relatively small.
When the average Q6 parameter is used to bias the dynamics a problems can occur. These averaged coordinates
cannot distinguish between the correct, single-nucleus pathway and a concerted pathway in which all the atoms
rearrange themselves into their solid-like configuration simultaneously. This second type of pathway would be
impossible in reality because there is a large entropic barrier that prevents concerted processes like this from
happening. However, in the finite sized systems that are commonly simulated this barrier is reduced substantially.
As a result in simulations where average Steinhardt parameters are biased there are often quite dramatic system
size effects
If one wants to simulate nucleation using some form on biased dynamics what is really required is an order parameter that measures:
• Whether or not the coordination spheres around atoms are ordered
• Whether or not the atoms that are ordered are clustered together in a crystalline nucleus
LOCAL_AVERAGE and NLINKS are variables that can be combined with the Steinhardt parameters allow to calculate variables that satisfy these requirements. LOCAL_Q6 is another variable that can be used in these sorts of
calculations. The LOCAL_Q6 parameter for a particular atom is a number that measures the extent to which the
orientation of the atoms in the first coordination sphere of an atom match the orientation of the central atom. It does
this by calculating the following quantity for each of the atoms in the system:
P
si =
j
σ(rij )
P6
∗
(i)q6m (j)
q6m
Pm=−6
σ(r
)
ij
j
where q6m (i) and q6m (j) are the sixth order Steinhardt vectors calculated for atom i and atom j respectively and the
asterisk denotes complex conjugation. The function σ(rij ) is a switchingfunction that acts on the distance between
atoms i and j . The parameters of this function should be set so that it the function is equal to one when atom j is
in the first coordination sphere of atom i and is zero otherwise. The sum in the numerator of this expression is the
dot product of the Steinhardt parameters for atoms i and j and thus measures the degree to which the orientations
of these adjacent atoms is correlated.
Generated by Doxygen
292
Collective Variables
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Or alternatively by using
Generated by Doxygen
5.5 MultiColvar
SPECIESA
SPECIESB
293
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
Generated by Doxygen
294
MIN
BETWEEN
HISTOGRAM
Collective Variables
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
(s
− s)m , where s is the
ment of a distribution is calculated using N
i
i=1
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Examples
The following command calculates the average value of the LOCAL_Q6 parameter for the 64 Lennard Jones atoms
in the system under study and prints this quantity to a file called colvar.
BEGIN_PLUMED_FILE
Q6 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q6
LOCAL_Q6 SPECIES=q6 SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LABEL=lq6
PRINT ARG=lq6.mean FILE=colvar
The following input calculates the distribution of LOCAL_Q6 parameters at any given time and outputs this information to a file.
BEGIN_PLUMED_FILE
Q6 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q6
LOCAL_Q6 SPECIES=q6 SWITCH={RATIONAL D_0=1.3 R_0=0.2} HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0
PRINT ARG=lq6.* FILE=colvar
The following calculates the LOCAL_Q6 parameters for atoms 1-5 only. For each of these atoms comparisons of
the geometry of the coordination sphere are done with those of all the other atoms in the system. The final quantity
is the average and is outputted to a file
Generated by Doxygen
5.5 MultiColvar
295
BEGIN_PLUMED_FILE
Q6 SPECIESA=1-5 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q6a
Q6 SPECIESA=6-64 SPECIESB=1-64 D_0=1.3 R_0=0.2 LABEL=q6b
LOCAL_Q6 SPECIES=q4a,q4b SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LOWMEM LABEL=w4
PRINT ARG=w6.* FILE=colvar
5.5.51
MCOLV_COMBINE
This is part of the multicolvar module
Calculate linear combinations of multiple multicolvars
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
Generated by Doxygen
296
Collective Variables
Compulsory keywords
DATA
the multicolvars you are calculating linear combinations for
COEFFICIENTS
( default=1.0 ) the coefficients to use for the various multicolvars
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
SUM
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
LESS_THAN
calculate the number of variables less than a certain target value. This quanP
tity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
MIN
MAX
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
is calculated using
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
Generated by Doxygen
5.5 MultiColvar
297
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
ALT_MIN
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
(s
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MOMENTS
min
Examples
5.5.52
MCOLV_PRODUCT
This is part of the multicolvar module
Calculate a product of multiple multicolvars
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Generated by Doxygen
298
Collective Variables
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
Compulsory keywords
DATA
the multicolvars you are calculating the product of
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
Generated by Doxygen
5.5 MultiColvar
299
SUM
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
MIN
MAX
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
min
is calculated using
LOWEST
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
ALT_MIN
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
(s
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MOMENTS
Generated by Doxygen
min
300
Collective Variables
Examples
5.5.53
NLINKS
This is part of the multicolvar module
Calculate number of pairs of atoms/molecules that are "linked"
In its simplest guise this coordinate calculates a coordination number. Each pair of atoms is assumed "linked" if
they are within some cutoff of each other. In more complex applications each entity is a vector and this quantity
measures whether pairs of vectors are (a) within a certain cutoff and (b) if the two vectors have similar orientations.
The vectors on individual atoms could be Steinhardt parameters (see Q3, Q4 and Q6) or they could describe some
internal vector in a molecule.
The atoms involved can be specified using
GROUP
. For more information on how to specify lists of atoms see Groups and Virtual Atoms
Or alternatively by using
GROUPA
GROUPB
Compulsory keywords
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
SERIAL
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Generated by Doxygen
5.5 MultiColvar
301
LOWMEM
( default=off ) lower the memory requirements
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
Examples
The following calculates how many bonds there are in a system containing 64 atoms and outputs this quantity to a
file.
BEGIN_PLUMED_FILE
DENSITY SPECIES=1-64 LABEL=d1
NLINKS ARG=d1 SWITCH={RATIONAL D_0=1.3 R_0=0.2} LABEL=dd
PRINT ARG=dd FILE=colvar
The following calculates how many pairs of neighboring atoms in a system containing 64 atoms have similar dispositions for the atoms in their coordination sphere. This calculation uses the dot product of the Q6 vectors on adjacent
atoms to measure whether or not two atoms have the same ``orientation"
BEGIN_PLUMED_FILE
Q6 SPECIES=1-64 SWITCH={RATIONAL D_0=1.3 R_0=0.2} LABEL=q6
NLINKS ARG=q6 SWITCH={RATIONAL D_0=1.3 R_0=0.2} LABEL=dd
PRINT ARG=dd FILE=colvar
5.5.54
PAMM
This is part of the pamm module
It is only available if you configure PLUMED with ./configure –enable-modules=pamm . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Probabilistic analysis of molecular motifs.
Probabilistic analysis of molecular motifs (PAMM) was introduced in this paper [pamm]. The essence of this
approach involves calculating some large set of collective variables for a set of atoms in a short trajectory and fitting
this data using a Gaussian Mixture Model. The idea is that modes in these distributions can be used to identify
features such as hydrogen bonds or secondary structure types.
The assumption within this implementation is that the fitting of the Gaussian mixture model has been done elsewhere
by a separate code. You thus provide an input file to this action which contains the means, covariance matrices
and weights for a set of Gaussian kernels, {φ}. The values and derivatives for the following set of quantities is then
computed:
φk
sk = P
i φi
Each of the φk is a Gaussian function that acts on a set of quantities calculated within a MultiColvar . These
might be TORSIONS, DISTANCES, ANGLES or any one of the many symmetry functions that are available within
Generated by Doxygen
302
Collective Variables
MultiColvar actions. These quantities are then inserted into the set of n kernels that are in the the input file. This
will be done for multiple sets of values for the input quantities and a final quantity will be calculated by summing the
above sk values or some transformation of the above. This sounds less complicated than it is and is best understood
by looking through the example given below.
Warning
Mixing MultiColvar actions that are periodic with variables that are not periodic has not been tested
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the set of PAMM variables will be referenced
using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly from the underlying set of PAMM variables. These quantities are calculated by employing the keywords listed below and they can be referenced elsewhere in the input file by using this Action's label followed by a dot and the name of the quantity. The particular
PAMM variable that should be averaged in a MEAN command or transformed by a switching function in a LESS←_THAN command is specified using the COMPONENT keyword. COMPONENT=1 refers to the PAMM variable in
which the first kernel in your input file is on the numerator, COMPONENT=2 refers to PAMM variable in which the
second kernel in the input file is on the numerator and so on. The same quantity can be calculated multiple times
for different PAMM components by a single PAMM action. In this case the relevant keyword must appear multiple
times on the input line followed by a numerical identifier i.e. MEAN1, MEAN2, ... The quantities calculated when
multiple MEAN commands appear on the input line can be reference elsewhere in the input file by using the name
of the quantity followed followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. Alternatively,
you can customize the labels of the quantities by using the LABEL keyword in the description of the keyword.
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
Generated by Doxygen
5.5 MultiColvar
303
Compulsory keywords
DATA
the multicolvars from which the pamm coordinates are calculated
CLUSTERS
REGULARISE
the name of the file that contains the definitions of all the clusters
( default=0.001 ) don't allow the denominator to be smaller then this value
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number of variables more than a certain target value. This quanP
tity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
SUM
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
MIN
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
Generated by Doxygen
304
MAX
LOWEST
Collective Variables
calculate the maximum value. To make this
continuous the maximum
quantity
P
is calculated using
= β log i exp sβi The value of β in this function is
max
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
ALT_MIN
calculate the minimum value. To make this quantity continuous the minimum
P
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
(s
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MOMENTS
min
Examples
In this example I will explain in detail what the following input is computing:
BEGIN_PLUMED_FILE
MOLINFO MOLTYPE=protein STRUCTURE=M1d.pdb
psi: TORSIONS ATOMS1=@psi-2 ATOMS2=@psi-3 ATOMS3=@psi-4
phi: TORSIONS ATOMS1=@phi-2 ATOMS2=@phi-3 ATOMS3=@phi-4
p: PAMM DATA=phi,psi CLUSTERS=clusters.dat MEAN1={COMPONENT=1} MEAN2={COMPONENT=2}
PRINT ARG=p.mean-1,mean-2 FILE=colvar
The best place to start our explanation is to look at the contents of the clusters.dat file
#! FIELDS height phi psi sigma_phi_phi sigma_phi_psi sigma_psi_phi sigma_psi_psi
#! SET multivariate von-misses
#! SET kerneltype gaussian
0.4
-1.0
-1.0
0.2
-0.1
-0.1
0.2
0.6
1.0
+1.0
0.1
-0.03
-0.03
0.1
Generated by Doxygen
5.5 MultiColvar
305
This files contains the parameters of two two-dimensional Gaussian functions. Each of these Gaussian kernels has
a weight, wk , a vector that specifies the position of its center, ck , and a covariance matrix, Σk . The φk functions
that we use to calculate our PAMM components are thus:
φk =
wk
exp −(s − ck )T Σ−1
k (s − ck )
Nk
In the above Nk is a normalization factor that is calculated based on Σ. The vector s is a vector of quantities that
are calculated by the TORSIONS actions. This vector must be two dimensional and in this case each component is
the value of a torsion angle. If we look at the two TORSIONS actions in the above we are calculating the φ and ψ
backbone torsional angles in a protein (Note the use of MOLINFO to make specification of atoms straightforward).
We thus calculate the values of our 2 {φ} kernels 3 times. The first time we use the φ and ψ angles in the second
residue of the protein, the second time it is the φ and ψ angles of the third residue of the protein and the third time
it is the φ and ψ angles of the fourth residue in the protein. The final two quantities that are output by the print
command, p.mean-1 and p.mean-2, are the averages over these three residues for the quantities:
s1 =
φ1
φ1 + φ2
s2 =
φ2
φ1 + φ2
and
There is a great deal of flexibility in this input. We can work with, and examine, any number of components, we can
use any set of collective variables and compute these PAMM variables and we can transform the PAMM variables
themselves in a large number of different ways when computing these sums.
5.5.55
POLYMER_ANGLES
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate a function to investigate the relative orientations of polymer angles
This CV takes the vectors calculated by a PLANES action as input and computes the following function of the relative
angles, θ , between the vectors that are normal to the pairs of input vectors:
s=
3 cos2 θ − 1
2
This average of this quantity over all the vectors in the first coordination sphere around each of the PLANES specified
is then calculated.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
Generated by Doxygen
306
Collective Variables
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Or alternatively by using
SPECIESA
SPECIESB
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
Generated by Doxygen
5.5 MultiColvar
307
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D←_0
R←_0
( default=0.0 ) The d_0 parameter of the switching function
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
MIN
BETWEEN
Generated by Doxygen
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
308
Collective Variables
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
(s
ment of a distribution is calculated using N
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Examples
The example below calculates a set of vectors using the PLANES action. The average number for the function s
defined above is then computed over the first coordination sphere of each of the centers of mass of the molecules
that were used to define the planes. Finally the average of these quantities is computed an printed to a file.
BEGIN_PLUMED_FILE
PLANES ...
MOL1=9,10,11
MOL2=89,90,91
MOL3=473,474,475
MOL4=1161,1162,1163
MOL5=1521,1522,1523
MOL6=1593,1594,1595
MOL7=1601,1602,1603
MOL8=2201,2202,2203
LABEL=m3
... PLANES
s3: POLYMER_ANGLES SPECIES=m3 LOWMEM SWITCH={RATIONAL R_0=0.6} MEAN
PRINT ARG=s3.mean FILE=colvar
5.5.56
SMAC
This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Calculate a variant on the SMAC collective variable discussed in [24]
The SMAC collective variable can be used to study the formation of molecular solids from either the melt or from
solution. The idea behind this variable is that what differentiates a molecular solid from a molecular liquid is an alignGenerated by Doxygen
5.5 MultiColvar
309
ment of internal vectors in neighboring molecules. In other words, the relative orientation of neighboring molecules
is no longer random as it is in a liquid. In a solid particular torsional angles between molecules are preferred. As
such this CV calculates the following average:
n
hP
io P
P
1−ψ
σ(r
)
ij
j6=i
j6=i σ(rij )
n Kn (θij )
P
si =
j6=i σ(rij )
In this expression rij is the distance between molecule i and molecule j and σ(rij ) is a switchingfunction that
acts on this distance. By including this switching function in the second summation in the numerator and in the
denominator we are thus ensuring that we calculate an average over the molecules in the first coordination sphere
of molecule i. All molecules in higher coordination sphere will essentially contribute zero to the sums in the above
expression because their σ(rij ) will be very small. ψ is also a switching function. The term including ψ in the
numerator is there to ensure that only those molecules that are attached to a reasonably large number of molecules.
It is important to include this "more than" switching function when you are simulating nucleation from solution
with this CV. Lastly, the $K_n functions are kernelfunctions that take the torsion angle, θij , between the internal
orientation vectors for molecules i and j as input. These kernel functions should be set so that they are equal to
one when the relative orientation of the molecules are as they are in the solid and equal to zero otherwise. The final
si quantity thus measures whether (on average) the molecules in the first coordination sphere around molecule i
are oriented as they would be in the solid. Furthermore, this Action is a multicolvar so you can calculate the si
values for all the molecules in your system simultaneously and then determine the average, the number less than
and so on.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
Generated by Doxygen
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
310
Collective Variables
The atoms involved can be specified using
SPECIES
this keyword is used for colvars such as coordination number. In that context it specifies that plumed
should calculate one coordination number for each of the atoms specified. Each of these coordination numbers specifies how many of the other specified atoms are within a certain cutoff of the
central atom. You can specify the atoms here as another multicolvar action or using a MultiColvar←Filter or ActionVolume action. When you do so the quantity is calculated for those atoms specified
in the previous multicolvar. This is useful if you would like to calculate the Steinhardt parameter for
those atoms that have a coordination number more than four for example
Or alternatively by using
SPECIESA
SPECIESB
this keyword is used for colvars such as the coordination number. In that context it species that
plumed should calculate one coordination number for each of the atoms specified in SPECIESA.
Each of these coordination numbers specifies how many of the atoms specifies using SPECIESB
is within the specified cutoff. As with the species keyword the input can also be specified using
the label of another multicolvar
this keyword is used for colvars such as the coordination number. It must appear with SPECIESA.
For a full explanation see the documentation for that keyword
Compulsory keywords
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D_0
( default=0.0 ) The d_0 parameter of the switching function
R_0
The r_0 parameter of the switching function
KERNEL
The kernels used in the function of the angle You can use multiple instances of this keyword
i.e. KERNEL1, KERNEL2, KERNEL3...
SWITCH_COORD
This keyword is used to define the coordination switching function.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
Generated by Doxygen
5.5 MultiColvar
311
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number of variables more than a certain target value. This quanP
tity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
MIN
BETWEEN
HISTOGRAM
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Examples
In the example below the orientation of the molecules in the system is determined by calculating the vector that
connects a pair of atoms. SMAC is then used to determine whether the molecules are sitting in a solid or liquid like
environment. We can determine whether the environment is solid or liquid like because in the solid the torsional
Generated by Doxygen
312
Collective Variables
angle between the bond vectors on adjacent molecules is close to 0 or π . The final quantity that is output to the
colvar file measures the number of molecules that have a SMAC parameter that is greater than 0.7. N.B. By using
the indices of three atoms for each of the MOL keywords below we are telling PLUMED to use the first two numbers
to determine the orientation of the molecule that will ultimately be used when calculating the θij terms in the formula
above. The atom with the third index meanwhile is used when we calculate rij .
BEGIN_PLUMED_FILE
MOLECULES ...
MOL1=9,10,9
MOL2=89,90,89
MOL3=473,474,473
MOL4=1161,1162,1161
MOL5=1521,1522,1521
MOL6=1593,1594,1593
MOL7=1601,1602,1601
MOL8=2201,2202,2201
LABEL=m3
... MOLECULES
SMAC ...
SPECIES=m3 LOWMEM
KERNEL1={GAUSSIAN CENTER=0 SIGMA=0.480} KERNEL2={GAUSSIAN CENTER=pi SIGMA=0.480}
SWITCH={RATIONAL R_0=0.6} MORE_THAN={RATIONAL R_0=0.7} SWITCH_COORD={EXP R_0=4}
LABEL=s2
... SMAC
PRINT ARG=s2.* FILE=colvar
This second example works in a way that is very similar to the previous command. Now, however, the orientation of
the molecules is determined by finding the plane that contains the positions of three atoms.
BEGIN_PLUMED_FILE
PLANES ...
MOL1=9,10,11
MOL2=89,90,91
MOL3=473,474,475
MOL4=1161,1162,1163
MOL5=1521,1522,1523
MOL6=1593,1594,1595
MOL7=1601,1602,1603
MOL8=2201,2202,2203
VMEAN
LABEL=m3
... PLANES
SMAC ...
SPECIES=m3 LOWMEM
KERNEL1={GAUSSIAN CENTER=0 SIGMA=0.480} KERNEL2={GAUSSIAN CENTER=pi SIGMA=0.480}
SWITCH={RATIONAL R_0=0.6} MORE_THAN={RATIONAL R_0=0.7} SWITCH_COORD={EXP R_0=3.0}
LABEL=s2
... SMAC
PRINT ARG=s2.* FILE=colvar
5.5.57
MTRANSFORM_BETWEEN
This is part of the multicolvar module
This action can be used to transform the colvar values calculated by a MultiColvar using a histogrambead
In this action each colvar, si , calculated by MultiColvar is transformed by a histogrambead function that is equal to
one if the colvar is within a certain range and which is equal to zero otherwise. In other words, we compute:
Generated by Doxygen
5.5 MultiColvar
313
Z
b
fi =
K
a
s − si
w
where a, b and w are parameters.
It is important to understand the distinction between what is done here and what is done by MFILTER_BETWEEN.
In MFILTER_BETWEEN a weight, wi for the colvar is calculated using the histogrambead. If one calculates the
MEAN for MFILTER_BETWEEN one is thus calculating:
P
fi si
µ = Pi
i fi
In this action by contrast the colvar is being transformed by the histogrambead. If one thus calculates a MEAN for
this action one computes:
PN
µ=
i=1
fi
N
In other words, you are calculating the mean for the transformed colvar.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere in
the input file by using the label.vmean
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
Generated by Doxygen
314
Collective Variables
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
LOWER
the lower boundary for the range of interest
UPPER
the upper boundary for the range of interest
SMEAR
( default=0.5 ) the amount by which to smear the value for kernel density estimation
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
ment of a distribution is calculated using N
(s
− s)m , where s is the
i
i=1
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MIN
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
MAX
min
is calculated using
ALT_MIN
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
Generated by Doxygen
min
5.5 MultiColvar
315
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
BEAD
This keywords is used if you want to employ an alternative to the function defined above. The following provides information on the histogrambead that are
available. When this keyword is present you no longer need the LOWER, U←PPER and SMEAR keywords.
Examples
The following input gives an example of how a MTRANSFORM_BETWEEN action can be used to duplicate functionality that is elsewhere in PLUMED.
BEGIN_PLUMED_FILE
DISTANCES ...
GROUPA=1-10 GROUPB=11-20
LABEL=d1
... DISTANCES
MTRANSFORM_BETWEEN DATA=d1 LOWER=1.0 UPPER=2.0 SMEAR=0.5
In this case you can achieve the same result by using:
BEGIN_PLUMED_FILE
DISTANCES ...
GROUPA=1-10 GROUPB=11-20
BETWEEN={GAUSSIAN LOWER=1.0 UPPER=2.0}
... DISTANCES
(see DISTANCES)
The advantage of MTRANSFORM_BETWEEN comes, however, if you want to use transformed colvars as input for
MULTICOLVARDENS
5.5.58
MTRANSFORM_LESS
This is part of the multicolvar module
This action can be used to transform the colvar values calculated by a MultiColvar using a switchingfunction
In this action each colvar, si , calculated by MultiColvar is transformed by a switchingfunction function that is equal to
one if the colvar is less than a certain target value and which is equal to zero otherwise. It is important to understand
the distinction between what is done here and what is done by MFILTER_LESS. In MFILTER_LESS a weight, wi
for the colvar is calculated using the switchingfunction. If one calculates the MEAN for MFILTER_LESS one is thus
calculating:
P
i σ(si )si
µ= P
i (si )
Generated by Doxygen
316
Collective Variables
where σ is the switchingfunction. In this action by contrast the colvar is being transformed by the switchingfunction.
If one thus calculates a MEAN for this action one computes:
PN
µ=
i=1 (si )
N
In other words, you are calculating the mean for the transformed colvar.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere in
the input file by using the label.vmean
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function
D_0
( default=0.0 ) The d_0 parameter of the switching function
R_0
The r_0 parameter of the switching function
Generated by Doxygen
5.5 MultiColvar
317
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
(s
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MIN
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
MAX
min
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
is calculated using
ALT_MIN
log
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
Generated by Doxygen
318
Collective Variables
Examples
The following input gives an example of how a MTRANSFORM_LESS action can be used to duplicate functionality
that is elsewhere in PLUMED.
BEGIN_PLUMED_FILE
DISTANCES ...
GROUPA=1-10 GROUPB=11-20
LABEL=d1
... DISTANCES
MTRANSFORM_LESS DATA=d1 SWITCH={GAUSSIAN D_0=1.5 R_0=0.00001}
In this case you can achieve the same result by using:
BEGIN_PLUMED_FILE
DISTANCES ...
GROUPA=1-10 GROUPB=11-20
LESS_THAN={GAUSSIAN D_0=1.5 R_0=0.00001}
... DISTANCES
(see DISTANCES)
The advantage of MTRANSFORM_LESS comes, however, if you want to use transformed colvars as input for
MULTICOLVARDENS
5.5.59
MTRANSFORM_MORE
This is part of the multicolvar module
This action can be used to transform the colvar values calculated by a MultiColvar using one minus a
switchingfunction
In this action each colvar, si , calculated by MultiColvar is transformed by a switchingfunction function that is equal
to one if the colvar is greater than a certain target value and which is equal to zero otherwise. It is important to
understand the distinction between what is done here and what is done by MFILTER_MORE. In MFILTER_MORE
a weight, wi for the colvar is calculated using the histogrambead. If one calculates the MEAN for MFILTER_MORE
one is thus calculating:
P
[1 − σ(si )]si
µ = Pi
i [1 − σ(si )]
where σ is the switchingfunction. In this action by contrast the colvar is being transformed by the switchingfunction.
If one thus calculates a MEAN for this action one computes:
PN
µ=
i=1
1 − σ(si )
N
In other words, you are calculating the mean for the transformed colvar.
Generated by Doxygen
5.5 MultiColvar
319
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere in
the input file by using the label.vmean
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
highest
HIGHEST
the lowest of the quantities calculated by this action
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input file
by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description
of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would be referenced elsewhere in the input file using label.moment-2, the third as label.moment-3,
etc.
Compulsory keywords
DATA
The multicolvar that calculates the set of base quantities that we are interested in
NN
( default=6 ) The n parameter of the switching function
MM
( default=0 ) The m parameter of the switching function; 0 implies 2∗NN
D_0
( default=0.0 ) The d_0 parameter of the switching function
R_0
The r_0 parameter of the switching function
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
Generated by Doxygen
320
Collective Variables
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
VMEAN
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
(s
− s)m , where s is the
ment of a distribution is calculated using N
i
i=1
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
MIN
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
MAX
min
is calculated using
ALT_MIN
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. When this keyword is present you no
longer need the NN, MM, D_0 and R_0 keywords.
Examples
The following input gives an example of how a MTRANSFORM_MORE action can be used to duplicate functionality
that is elsewhere in PLUMED.
Generated by Doxygen
5.5 MultiColvar
321
BEGIN_PLUMED_FILE
DISTANCES ...
GROUPA=1-10 GROUPB=11-20
LABEL=d1
... DISTANCES
MTRANSFORM_MORE DATA=d1 SWITCH={GAUSSIAN D_0=1.5 R_0=0.00001}
In this case you can achieve the same result by using:
BEGIN_PLUMED_FILE
DISTANCES ...
GROUPA=1-10 GROUPB=11-20
MORE_THAN={GAUSSIAN D_0=1.5 R_0=0.00001}
... DISTANCES
(see DISTANCES)
The advantage of MTRANSFORM_MORE comes, however, if you want to use transformed colvars as input for
MULTICOLVARDENS
5.5.60
LWALLS
This is part of the manyrestraints module
It is only available if you configure PLUMED with ./configure –enable-modules=manyrestraints . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Add LOWER_WALLS restraints on all the multicolvar values
This action takes the set of values calculated by the colvar specified by label in the DATA keyword and places a
restraint on each quantity, x, with the following functional form:
k((x − a + o)/s)e
k (KAPPA) is an energy constant in internal unit of the code, s (EPS) a rescaling factor and e (EXP) the exponent
determining the power law. By default: EXP = 2, EPS = 1.0, OFF = 0.
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potentials
In addition the following quantities can be calculated by employing the keywords listed below
Generated by Doxygen
322
Collective Variables
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
Compulsory keywords
DATA
certain actions in plumed work by calculating a list of variables and summing over them. This particular action can be used to calculate functions of these base variables or prints them to a file. This
keyword thus takes the label of one of those such variables as input.
AT
the radius of the sphere
KAPPA
the force constant for the wall. The k_i in the expression for a wall.
OFFSET
( default=0.0 ) the offset for the start of the wall. The o_i in the expression for a wall.
EXP
( default=2.0 ) the powers for the walls. The e_i in the expression for a wall.
EPS
( default=1.0 ) the values for s_i in the expression for a wall
Options
Generated by Doxygen
5.5 MultiColvar
323
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Examples
The following set of commands can be used to stop any of the 800 atoms in group A from moving more than 2.46425
nm in the z direction from atom 34137. This is done by adding a lower wall on the z-distance between all the atoms
in group A and the position of 34137.
BEGIN_PLUMED_FILE
l: ZDISTANCES GROUPA=1-800 GROUPB=34137 NOPBC
LWALLS DATA=l AT=2.46465 KAPPA=150.0 EXP=2 EPS=1 OFFSET=0 LABEL=lwall
5.5.61
UWALLS
This is part of the manyrestraints module
It is only available if you configure PLUMED with ./configure –enable-modules=manyrestraints . Furthermore, this feature is still being developed so take care when using it and report any problems on the
mailing list.
Add UPPER_WALLS restraints on all the multicolvar values
This action takes the set of values calculated by the colvar specified by label in the DATA keyword and places a
restraint on each quantity, x, with the following functional form:
k((x − a + o)/s)e
k (KAPPA) is an energy constant in internal unit of the code, s (EPS) a rescaling factor and e (EXP) the exponent
determining the power law. By default: EXP = 2, EPS = 1.0, OFF = 0.
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potentials
In addition the following quantities can be calculated by employing the keywords listed below
Generated by Doxygen
324
Collective Variables
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
Compulsory keywords
DATA
certain actions in plumed work by calculating a list of variables and summing over them. This particular action can be used to calculate functions of these base variables or prints them to a file. This
keyword thus takes the label of one of those such variables as input.
AT
the radius of the sphere
KAPPA
the force constant for the wall. The k_i in the expression for a wall.
OFFSET
( default=0.0 ) the offset for the start of the wall. The o_i in the expression for a wall.
EXP
( default=2.0 ) the powers for the walls. The e_i in the expression for a wall.
EPS
( default=1.0 ) the values for s_i in the expression for a wall
Options
Generated by Doxygen
5.6 Exploiting contact matrices
325
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Examples
The following set of commands can be used to stop a cluster composed of 20 atoms subliming. The position of the
center of mass of the cluster is calculated by the COM command labelled c1. The DISTANCES command labelled
d1 is then used to calculate the distance between each of the 20 atoms in the cluster and the center of mass of the
cluster. These distances are then passed to the UWALLS command, which adds a UPPER_WALLS restraint on
each of them and thereby prevents each of them from moving very far from the center of mass of the cluster.
BEGIN_PLUMED_FILE
COM ATOMS=1-20 LABEL=c1
DISTANCES GROUPA=c1 GROUPB=1-20 LABEL=d1
UWALLS DATA=d1 AT=2.5 KAPPA=0.2 LABEL=sr
5.6
Exploiting contact matrices
A contact matrix is an N × N matrix in which the ith, j th element tells you whether or not the ith and j th
atoms/molecules from a set of N atoms/molecules are adjacent or not. There are various ways of defining whether
a pair of atoms/molecules are adjacent or not. For example we can say two atoms are adjacent if the distance
between them is less than some cutoff. Alternatively, if we have a have a pair of molecules, we might state they are
adjacent if their centers of mass are within a certain cutoff and if the two molecules have the same orientation. Two
electronegative atoms might be said to be adjacent if there is a hydrogen bond between them. For these reasons
then PLUMED contains all of the following methods for calculating an adjacency matrix
ALIGNED_MATRIX
Adjacency matrix in which two molecule are adjacent if they are within a certain cutoff
and if they have the same orientation.
CONTACT_MATRIX
Adjacency matrix in which two atoms are adjacent if they are within a certain cutoff.
HBOND_MATRIX
Adjacency matrix in which two atoms are adjacent if there is a hydrogen bond between
them.
Adjacency matrix in which two electronegative atoms are adjacent if they are hydrogen
bonded
Adjacency matrix in which two molecules are adjacent if they are within a certain cutoff
and if the angle between them is within certain ranges.
HBPAMM_MATRIX
SMAC_MATRIX
TOPOLOGY_MATRIX
Adjacency matrix in which two atoms are adjacent if they are connected topologically
Once you have calculated an adjacency matrix you can then perform any one of the following operations on this
object in order to reduce it to a scalar number or a set of connected components.
CLUSTER_WITHSURFACE
COLUMNSUMS
DFSCLUSTERING
Generated by Doxygen
Take a connected component that was found using a clustering algorithm and
create a new cluster that contains those atoms that are in the cluster together
with those atoms that are within a certain cutoff of the cluster.
Sum the columns of a contact matrix
Find the connected components of the matrix using the depth first search clustering algorithm.
326
Collective Variables
ROWSUMS
Sum the rows of a adjacency matrix.
SPRINT
Calculate SPRINT topological variables from an adjacency matrix.
If the function you have chosen reduces your contact matrix to a set of connected components you then need a
method to convert these connected components into a scalar number or to output this information to a file. The
various things that you can do with a set of connected components are listed below:
CLUSTER_DIAMETER
Print out the diameter of one of the connected components
CLUSTER_DISTRIBUTION
Calculate functions of the distribution of properties in your connected components.
Gives the number of atoms in the connected component
CLUSTER_NATOMS
CLUSTER_PROPERTIES
Calculate properties of the distribution of some quantities that are part of a connected component
DUMPGRAPH
Write out the connectivity of the nodes in the graph in dot format.
OUTPUT_CLUSTER
Output the indices of the atoms in one of the clusters identified by a clustering
object
5.6.1
ALIGNED_MATRIX
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Adjacency matrix in which two molecule are adjacent if they are within a certain cutoff and if they have the same
orientation.
As discussed in the section of the manual on Exploiting contact matrices a useful tool for developing complex collective variables is the notion of the so called adjacency matrix. An adjacency matrix is an N × N matrix in which
the ith, j th element tells you whether or not the ith and j th atoms/molecules from a set of N atoms/molecules are
adjacent or not. These matrices can then be further analyzed using a number of other algorithms as is detailed in
[30].
For this action the elements of the adjacency matrix are calculated using:
aij = σ1 (|rij |)σ2 (vi .vj )
This form of adjacency matrix can only be used if the input species are objects that lie at a point in space and
that have an orientation, v. These orientations might represent the orientation of a molecule, which could be
calculated using MOLECULES or PLANES, or it might be the complex vectors calculated using the Steinhardt
parameters Q3, Q4 or Q6. In the expression above rij is the vector connecting the points in space where objects
i and j find themselves and σ1 is a switchingfunction that acts upon the magnitude of this vector. σ2 is a second
switchingfunction that acts on the dot product of the directors of the vectors that define the orientations of objects i
and j .
The atoms involved can be specified using
Generated by Doxygen
5.6 Exploiting contact matrices
ATOMS
327
The list of molecules for which you would like to calculate the contact matrix. The molecules involved
must have an orientation so your list will be a list of the labels of MultiColvar or MultiColvar functions
as PLUMED calculates the orientations of molecules within these operations. Please note also that
the majority of MultiColvar and MultiColvar functions do not calculate a molecular orientation.. For
more information on how to specify lists of atoms see Groups and Virtual Atoms
Or alternatively by using
ATOMSA
ATOMSB
The list of molecules that you would like to use for the rows of the contact matrix. The molecules
involved must have an orientation so your list will be a list of the labels of MultiColvar or
MultiColvar functions as PLUMED calculates the orientations of molecules within these operations.
Please note also that the majority of MultiColvar and MultiColvar functions do not calculate a molecular orientation.
The list of molecules that you would like to use for the columns of the contact matrix. The
molecules involved must have an orientation so your list will be a list of the labels of MultiColvar
or MultiColvar functions as PLUMED calculates the orientations of molecules within these operations. Please note also that the majority of MultiColvar and MultiColvar functions do not calculate a
molecular orientation.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
SERIAL
TIMINGS
HIGHMEM
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) use a more memory intensive version of this collective variable
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. You can use multiple instances of this
keyword i.e. SWITCH1, SWITCH2, SWITCH3...
ORIENTATION_SWITCH
A switching function that transforms the dot product of the input vectors. You
can use multiple instances of this keyword i.e. ORIENTATION_SWITCH1, O←RIENTATION_SWITCH2, ORIENTATION_SWITCH3...
Examples
The example input below is necessarily but gives you an idea of what can be achieved using this action. The
orientations and positions of four molecules are defined using the MOLECULES action as the position of the centers
of mass of the two atoms specified and the direction of the vector connecting the two atoms that were specified. A
4 × 4 matrix is then computed using the formula above. The ij -element of this matrix tells us whether or not atoms
i and j are within 0.1 nm of each other and whether or not the dot-product of their orientation vectors is greater than
0.5. The sum of the rows of this matrix are then computed. The sums of the ith row of this matrix tells us how many
of the molecules that are within the first coordination sphere of molecule i have an orientation that is similar to that
of molecule i. We thus calculate the number of these "coordination numbers" that are greater than 1.0 and output
this quantity to a file.
Generated by Doxygen
328
Collective Variables
BEGIN_PLUMED_FILE
m1: MOLECULES MOL1=1,2 MOL2=3,4 MOL3=5,6 MOL4=7,8
mat: ALIGNED_MATRIX ATOMS=m1 SWITCH={RATIONAL R_0=0.1} ORIENTATION_SWITCH={RATIONAL R_0=0.1 D_MAX=0.5}
row: ROWSUMS MATRIX=mat MORE_THAN={RATIONAL D_0=1.0 R_0=0.1}
PRINT ARG=row.* FILE=colvar
5.6.2
CONTACT_MATRIX
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Adjacency matrix in which two atoms are adjacent if they are within a certain cutoff.
As discussed in the section of the manual on Exploiting contact matrices a useful tool for developing complex collective variables is the notion of the so called adjacency matrix. An adjacency matrix is an N × N matrix in which
the ith, j th element tells you whether or not the ith and j th atoms/molecules from a set of N atoms/molecules are
adjacent or not. These matrices can then be further analyzed using a number of other algorithms as is detailed in
[30].
For this action the elements of the contact matrix are calculated using:
aij = σ(|rij |)
where |rij | is the magnitude of the vector connecting atoms i and j and where σ is a switchingfunction.
The atoms involved can be specified using
ATOMS
The list of atoms for which you would like to calculate the contact matrix. The atoms involved must
be specified as a list of labels of MultiColvar or labels of a MultiColvar functions actions. If you would
just like to use the atomic positions you can use a DENSITY command to specify a group of atoms.
Specifying your atomic positions using labels of other MultiColvar or MultiColvar functions commands
is useful, however, as you can then exploit a much wider variety of functions of the contact matrix as
described in Exploiting contact matrices. For more information on how to specify lists of atoms see
Groups and Virtual Atoms
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
SERIAL
TIMINGS
HIGHMEM
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) use a more memory intensive version of this collective variable
Generated by Doxygen
5.6 Exploiting contact matrices
SWITCH
329
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. You can use multiple instances of this
keyword i.e. SWITCH1, SWITCH2, SWITCH3...
Examples
The input shown below calculates a 6 × 6 matrix whose elements are equal to one if atom i and atom j are within
0.3 nm of each other and which is zero otherwise. The columns in this matrix are then summed so as to give
the coordination number for each atom. The final quantity output in the colvar file is thus the average coordination
number.
BEGIN_PLUMED_FILE
aa: CONTACT_MATRIX ATOMS=1-6 SWITCH={EXP D_0=0.2 R_0=0.1 D_MAX=0.66}
COLUMNSUMS MATRIX=mat MEAN LABEL=csums
PRINT ARG=csums.* FILE=colvar
5.6.3
HBOND_MATRIX
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Adjacency matrix in which two atoms are adjacent if there is a hydrogen bond between them.
As discussed in the section of the manual on Exploiting contact matrices a useful tool for developing complex collective variables is the notion of the so called adjacency matrix. An adjacency matrix is an N × N matrix in which
the ith, j th element tells you whether or not the ith and j th atoms/molecules from a set of N atoms/molecules are
adjacent or not. These matrices can then be further analyzed using a number of other algorithms as is detailed in
[30].
For this action the elements of the adjacency matrix are calculated using:
aij = σoo (|rij |)
N
X
σoh (|rik |)σθ (θkij )
k=1
This expression was derived by thinking about how to detect if there is a hydrogen bond between atoms i and j . The
notion is that if the hydrogen bond is present atoms i and j should be within a certain cutoff distance. In addition,
there should be a hydrogen within a certain cutoff distance of atom i and this hydrogen should lie on or close to the
vector connecting atoms i and j . As such σoo (|rij |) is a switchingfunction that acts on the modulus of the vector
connecting atom i to atom j . The sum over k then runs over all the hydrogen atoms that are specified using using
HYDROGEN keyword. σoh (|rik |) is a switchingfunction that acts on the modulus of the vector connecting atom i to
atom k and σθ (θkij ) is a switchingfunction that acts on the angle between the vector connecting atoms i and j and
the vector connecting atoms i and k .
It is important to note that hydrogen bonds, unlike regular bonds, are asymmetric. In other words, the hydrogen atom
does not sit at the mid point between the two other atoms in this three-center bond. As a result of this adjacency
matrices calculated using HBOND_MATRIX are not symmetric like those calculated by CONTACT_MATRIX. One
consequence of this fact is that the quantities found by performing ROWSUMS and COLUMNSUMS on a square
HBOND_MATRIX are not the same as they would be if you performed ROWSUMS and COLUMNSUMS on a square
CONTACT_MATRIX.
Generated by Doxygen
330
Collective Variables
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
sum
SUM
the sum of values
The atoms involved can be specified using
ATOMS
The list of atoms which can be part of a hydrogen bond. When this command is used the set
of atoms that can donate a hydrogen bond is assumed to be the same as the set of atoms
that can form hydrogen bonds. The atoms involved must be specified as a list of labels of
MultiColvar or labels of a MultiColvar functions actions. If you would just like to use the atomic
positions you can use a DENSITY command to specify a group of atoms. Specifying your
atomic positions using labels of other MultiColvar or MultiColvar functions commands is useful,
however, as you can then exploit a much wider variety of functions of the contact matrix as
described in Exploiting contact matrices. For more information on how to specify lists of atoms
see Groups and Virtual Atoms
HYDROGENS
The list of hydrogen atoms that can form part of a hydrogen bond. The atoms must be specified
using a comma separated list, an index range or by using a GROUP. A list of hydrogen
atoms is always required even if you specify the other atoms using DONORS and ACC←EPTORS as described below.. For more information on how to specify lists of atoms see
Groups and Virtual Atoms
Or alternatively by using
DONORS
The list of atoms which can donate a hydrogen bond. The atoms involved must be specified
as a list of labels of MultiColvar or labels of a MultiColvar functions actions. If you would just
like to use the atomic positions you can use a DENSITY command to specify a group of atoms.
Specifying your atomic positions using labels of other MultiColvar or MultiColvar functions commands is useful, however, as you can then exploit a much wider variety of functions of the
contact matrix as described in Exploiting contact matrices
ACCEPTORS
The list of atoms which can accept a hydrogen bond. The atoms involved must be specified
as a list of labels of MultiColvar or labels of a MultiColvar functions actions. If you would just
like to use the atomic positions you can use a DENSITY command to specify a group of atoms.
Specifying your atomic positions using labels of other MultiColvar or MultiColvar functions commands is useful, however, as you can then exploit a much wider variety of functions of the
contact matrix as described in Exploiting contact matrices
Generated by Doxygen
5.6 Exploiting contact matrices
331
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
SERIAL
TIMINGS
HIGHMEM
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) use a more memory intensive version of this collective variable
SWITCH
The switchingfunction that specifies how close a pair of atoms must be together
for there to be a hydrogen bond between them You can use multiple instances
of this keyword i.e. SWITCH1, SWITCH2, SWITCH3...
HSWITCH
The switchingfunction that specifies how close the hydrogen must be to the
donor atom of the hydrogen bond for it to be considered a hydrogen bond You
can use multiple instances of this keyword i.e. HSWITCH1, HSWITCH2, HS←WITCH3...
A switchingfunction that is used to specify what the angle between the vector
connecting the donor atom to the acceptor atom and the vector connecting the
donor atom to the hydrogen must be in order for it considered to be a hydrogen
bond You can use multiple instances of this keyword i.e. ASWITCH1, ASWI←TCH2, ASWITCH3...
ASWITCH
SUM
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
Examples
The following input can be used to analyze the number of hydrogen bonds each of the oxygen atoms in a box of
water participates in. Each water molecule can participate in a hydrogen bond in one of two ways. It can either
donate one of its hydrogen atom to the neighboring oxygen or it can accept a bond between the hydrogen of a
neighboring water molecule and its own oxygen. The input below allows you to output information on the number of
hydrogen bonds each of the water molecules donates and accepts. This information is output in two xyz files which
each contain five columns of data. The first four of these columns are a label for the atom and the x, y and z position
of the oxygen. The last column is then the number of accepted/donated hydrogen bonds.
BEGIN_PLUMED_FILE
mat: HBOND_MATRIX ATOMS=1-192:3 HYDROGENS=2-192:3,3-192:3 SWITCH={RATIONAL R_0=3.20} HSWITCH={RATIONAL R_0=2.3
rsums: ROWSUMS MATRIX=mat MEAN
csums: COLUMNSUMS MATRIX=mat MEAN
DUMPMULTICOLVAR DATA=rsums FILE=donors.xyz
DUMPMULTICOLVAR DATA=csums FILE=acceptors.x
5.6.4
HBPAMM_MATRIX
This is part of the pamm module
It is only available if you configure PLUMED with ./configure –enable-modules=pamm . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Generated by Doxygen
332
Collective Variables
Adjacency matrix in which two electronegative atoms are adjacent if they are hydrogen bonded
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
sum
SUM
the sum of values
The atoms involved can be specified using
SITES
The list of atoms which can be part of a hydrogen bond. When this command is used the set of
atoms that can donate a hydrogen bond is assumed to be the same as the set of atoms that can
form hydrogen bonds. The atoms involved must be specified as a list of labels of MultiColvar or labels
of a MultiColvar functions actions. If you would just like to use the atomic positions you can use a
DENSITY command to specify a group of atoms. Specifying your atomic positions using labels of
other MultiColvar or MultiColvar functions commands is useful, however, as you can then exploit a
much wider variety of functions of the contact matrix as described in Exploiting contact matrices
Or alternatively by using
DONORS
The list of atoms which can donate a hydrogen bond. The atoms involved must be specified
as a list of labels of MultiColvar or labels of a MultiColvar functions actions. If you would just
like to use the atomic positions you can use a DENSITY command to specify a group of atoms.
Specifying your atomic positions using labels of other MultiColvar or MultiColvar functions commands is useful, however, as you can then exploit a much wider variety of functions of the
contact matrix as described in Exploiting contact matrices
ACCEPTORS
The list of atoms which can accept a hydrogen bond. The atoms involved must be specified
as a list of labels of MultiColvar or labels of a MultiColvar functions actions. If you would just
like to use the atomic positions you can use a DENSITY command to specify a group of atoms.
Specifying your atomic positions using labels of other MultiColvar or MultiColvar functions commands is useful, however, as you can then exploit a much wider variety of functions of the
contact matrix as described in Exploiting contact matrices
Or alternatively by using
Generated by Doxygen
5.6 Exploiting contact matrices
HYDROGENS
333
The list of hydrogen atoms that can form part of a hydrogen bond. The atoms must be specified
using a comma separated list, an index range or by using a GROUP. For more information on
how to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
CLUSTERS
the name of the file that contains the definitions of all the kernels for PAMM You can use
multiple instances of this keyword i.e. CLUSTERS1, CLUSTERS2, CLUSTERS3...
REGULARISE
( default=0.001 ) don't allow the denominator to be smaller then this value
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
SERIAL
TIMINGS
HIGHMEM
SUM
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) use a more memory intensive version of this collective variable
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
Examples
5.6.5
SMAC_MATRIX
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Adjacency matrix in which two molecules are adjacent if they are within a certain cutoff and if the angle between
them is within certain ranges.
In this case the elements of the adjacency matrix are calculated using:
Aij = σ(rij )
X
Kn (θij )
n
In this expression rij is the distance between molecule i and molecule j and σ(rij is a switchingfunction that
acts on this distance. The $K_n functions are kernelfunctions that take the torsion angle, θij , between the internal
Generated by Doxygen
334
Collective Variables
orientation vectors for molecules i and j as input. These kernel functions should be set so that they are equal to
one when the relative orientation of the molecules are as they are in the solid and equal to zero otherwise. As the
above matrix element is a product of functions it is only equal to one when the centers of mass of molecules i and
j are with a certain distance of each other and when the molecules are aligned in some desirable way.
The atoms involved can be specified using
ATOMS
The list of molecules for which you would like to calculate the contact matrix. The molecules involved
must have an orientation so your list will be a list of the labels of MultiColvar or MultiColvar functions
as PLUMED calculates the orientations of molecules within these operations. Please note also that
the majority of MultiColvar and MultiColvar functions do not calculate a molecular orientation.. For
more information on how to specify lists of atoms see Groups and Virtual Atoms
Or alternatively by using
ATOMSA
ATOMSB
The list of molecules that you would like to use for the rows of the contact matrix. The molecules
involved must have an orientation so your list will be a list of the labels of MultiColvar or
MultiColvar functions as PLUMED calculates the orientations of molecules within these operations.
Please note also that the majority of MultiColvar and MultiColvar functions do not calculate a molecular orientation.
The list of molecules that you would like to use for the columns of the contact matrix. The
molecules involved must have an orientation so your list will be a list of the labels of MultiColvar
or MultiColvar functions as PLUMED calculates the orientations of molecules within these operations. Please note also that the majority of MultiColvar and MultiColvar functions do not calculate a
molecular orientation.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
SERIAL
TIMINGS
HIGHMEM
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) use a more memory intensive version of this collective variable
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. You can use multiple instances of this
keyword i.e. SWITCH1, SWITCH2, SWITCH3...
KERNEL
The various kernels that are used to determine whether or not the molecules
are aligned You can use multiple instances of this keyword i.e. KERNEL1, K←ERNEL2, KERNEL3...
Examples
In the following example an adjacency matrix is constructed in which the (i, j) element is equal to one if molecules
Generated by Doxygen
5.6 Exploiting contact matrices
335
i and j are within 6 angstroms of each other and if the torsional angle between the orientations of these molecules
is close to 0 or π . The various connected components of this matrix are determined using the DFSCLUSTERING
algorithm and then the size of the largest cluster of connects molecules is output to a colvar file
BEGIN_PLUMED_FILE
UNITS LENGTH=A
MOLECULES ...
MOL1=1,2,1
MOL2=5,6,5
MOL3=9,10,9
MOL4=13,14,13
MOL5=17,18,17
LABEL=m1
... MOLECULES
SMAC_MATRIX ...
ATOMS=m1 SWITCH={RATIONAL D_0=5.99 R_0=0.1 D_MAX=6.0}
KERNEL1={TRIANGULAR CENTER=0 SIGMA=1.0} KERNEL2={TRIANGULAR CENTER=pi SIGMA=0.6}
LABEL=smacm
... SMAC_MATRIX
dfs1: DFSCLUSTERING MATRIX=smacm
cc2: CLUSTER_NATOMS CLUSTERS=dfs1 CLUSTER=1
PRINT ARG=smac.*,cc1.*,cc2 FILE=colvar
5.6.6
TOPOLOGY_MATRIX
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Adjacency matrix in which two atoms are adjacent if they are connected topologically
The atoms involved can be specified using
NODES
The list of atoms for which you would like to calculate the contact matrix. The atoms involved must
be specified as a list of labels of MultiColvar or labels of a MultiColvar functions actions. If you would
just like to use the atomic positions you can use a DENSITY command to specify a group of atoms.
Specifying your atomic positions using labels of other MultiColvar or MultiColvar functions commands
is useful, however, as you can then exploit a much wider variety of functions of the contact matrix as
described in Exploiting contact matrices. For more information on how to specify lists of atoms see
Groups and Virtual Atoms
ATOMS
. For more information on how to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
DENSITY_THRESHOLD
SIGMA
the width of the function to be used for kernel density estimation
KERNEL
( default=gaussian ) the type of kernel function to be used
Generated by Doxygen
336
Collective Variables
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
SERIAL
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) use a more memory intensive version of this collective variable
HIGHMEM
SWITCH
This keyword is used if you want to employ an alternative to the continuous
switching function defined above. The following provides information on the
switchingfunction that are available. You can use multiple instances of this
keyword i.e. SWITCH1, SWITCH2, SWITCH3...
RADIUS
You can use multiple instances of this keyword i.e. RADIUS1, RADIUS2, RA←DIUS3...
a switching function on (rij · rik − 1)/rij You can use multiple instances of this
keyword i.e. CYLINDER_SWITCH1, CYLINDER_SWITCH2, CYLINDER_S←WITCH3...
the size to use for the bins You can use multiple instances of this keyword i.e.
BIN_SIZE1, BIN_SIZE2, BIN_SIZE3...
CYLINDER_SWITCH
BIN_SIZE
Examples
5.6.7
CLUSTER_WITHSURFACE
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Take a connected component that was found using a clustering algorithm and create a new cluster that contains
those atoms that are in the cluster together with those atoms that are within a certain cutoff of the cluster.
As discussed in the section of the manual on Exploiting contact matrices a useful tool for developing complex collective variables is the notion of the so called adjacency matrix. An adjacency matrix is an N × N matrix in which
the ith, j th element tells you whether or not the ith and j th atoms/molecules from a set of N atoms/molecules are
adjacent or not. When analyzing these matrix we can treat them as a graph and find connected components using
some clustering algorithm. This action is used in tandem with this form of analysis and takes one of the connected
components that was found during this analysis and creates a new cluster that includes all the atoms within the connected component that was found together that were within a certain cutoff distance of the atoms in the connected
component. This form of analysis has been used successfully in the forward flux sampling simulations described in
this paper [31]
Compulsory keywords
CLUSTERS
the label of the action that does the clustering
RCUT_SURF
you also have the option to find the atoms on the surface of the cluster. An atom must be within
this distance of one of the atoms of the cluster in order to be considered a surface
atomby Doxygen
Generated
5.6 Exploiting contact matrices
337
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Examples
The following input uses PLUMED to calculate a adjacency matrix that connects a pair of atoms if they both have a
coordination number that is less than 13.5 and if they are within 0.38 nm of each other. Depth first search clustering
is used to find the connected components in this matrix. The number of atoms with indices that are between 1 and
1996 and that are either in the second largest cluster or that are within within 0.3 nm of one of the atoms within the
the second largest cluster are then counted and this number of atoms is output to a file called size. In addition the
indices of the atoms that were counted are output to a file called dfs2.dat.
BEGIN_PLUMED_FILE
c1: COORDINATIONNUMBER SPECIES=1-1996 SWITCH={CUBIC D_0=0.34 D_MAX=0.38}
cf: MFILTER_LESS DATA=c1 SWITCH={CUBIC D_0=13 D_MAX=13.5}
mat: CONTACT_MATRIX ATOMS=cf SWITCH={CUBIC D_0=0.34 D_MAX=0.38}
dfs: DFSCLUSTERING MATRIX=mat
clust2a: CLUSTER_WITHSURFACE CLUSTERS=dfs RCUT_SURF=0.3
size2a: CLUSTER_NATOMS CLUSTERS=clust2a CLUSTER=2
PRINT ARG=size2a FILE=size FMT=%8.4f
OUTPUT_CLUSTER CLUSTERS=clust2a CLUSTER=2 FILE=dfs2.dat
5.6.8
COLUMNSUMS
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Sum the columns of a contact matrix
As discussed in the section of the manual on Exploiting contact matrices a useful tool for developing complex collective variables is the notion of the so called adjacency matrix. An adjacency matrix is an N × N matrix in which
the ith, j th element tells you whether or not the ith and j th atoms/molecules from a set of N atoms/molecules are
adjacent or not. This action allows you to calculate the sum of the columns in this adjacency matrix and to then
calculate further functions of these quantities.
Description of components
Generated by Doxygen
338
Collective Variables
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
Compulsory keywords
MAT←RIX
the action that calculates the adjacency matrix vessel we would like to analyze
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
Generated by Doxygen
5.6 Exploiting contact matrices
339
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
ALT_MIN
calculate the minimum value. To make this quantity continuous the minimum
P
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
MIN
MAX
min
min
is calculated using
LESS_THAN
MORE_THAN
BETWEEN
HISTOGRAM
Generated by Doxygen
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
340
Collective Variables
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
Examples
The first instruction in the following input file tells PLUMED to compute a 10 × 10 matrix in which the ij -element
tells you whether atoms i and j are within 1.0 nm of each other. The numbers in each of this rows are then
added together and the average value is computed. As such the following input provides an alternative method for
calculating the coordination numbers of atoms 1 to 10.
BEGIN_PLUMED_FILE
mat: CONTACT_MATRIX ATOMS=1-10 SWITCH={RATIONAL R_0=1.0}
rsums: COLUMNSUMS MATRIX=mat MEAN
PRINT ARG=rsums.* FILE=colvar
The following input demonstrates another way that an average coordination number can be computed. This input
calculates the number of atoms with indices between 1 and 5 that are within the first coordination spheres of each of
the atoms within indices between 6 and 15. The average coordination number is then calculated from these fifteen
coordination numbers and this quantity is output to a file.
BEGIN_PLUMED_FILE
mat2: CONTACT_MATRIX ATOMSA=1-5 ATOMSB=6-15 SWITCH={RATIONAL R_0=1.0}
rsums: COLUMNSUMS MATRIX=mat2 MEAN
PRINT ARG=rsums.* FILE=colvar
5.6.9
DFSCLUSTERING
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Find the connected components of the matrix using the depth first search clustering algorithm.
As discussed in the section of the manual on Exploiting contact matrices a useful tool for developing complex collective variables is the notion of the so called adjacency matrix. An adjacency matrix is an N × N matrix in which
the ith, j th element tells you whether or not the ith and j th atoms/molecules from a set of N atoms/molecules are
adjacent or not. As detailed in [30] these matrices provide a representation of a graph and can thus can be analyzed
using tools from graph theory. This particular action performs a depth first search clustering to find the connected
components of this graph. You can read more about depth first search here:
https://en.wikipedia.org/wiki/Depth-first_search
This action is useful if you are looking at a phenomenon such as nucleation where the aim is to detect the sizes of
the crystalline nuclei that have formed in your simulation cell.
Generated by Doxygen
5.6 Exploiting contact matrices
341
Compulsory keywords
MATRIX
the action that calculates the adjacency matrix vessel we would like to analyze
MAXCONNECT
( default=0 ) maximum number of connections that can be formed by any given node in the
graph. By default this is set equal to zero and the number of connections is set equal to the
number of nodes. You only really need to set this if you are working with a very large system
and memory is at a premium
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Examples
The input below calculates the coordination numbers of atoms 1-100 and then computes the an adjacency matrix
whose elements measures whether atoms i and j are within 0.55 nm of each other. The action labelled dfs then
treats the elements of this matrix as zero or ones and thus thinks of the matrix as defining a graph. This dfs action
then finds the largest connected component in this graph. The sum of the coordination numbers for the atoms in
this largest connected component are then computed and this quantity is output to a colvar file. The way this input
can be used is described in detail in [30].
BEGIN_PLUMED_FILE
lq: COORDINATIONNUMBER SPECIES=1-100 SWITCH={CUBIC D_0=0.45 D_MAX=0.55} LOWMEM
cm: CONTACT_MATRIX ATOMS=lq SWITCH={CUBIC D_0=0.45 D_MAX=0.55}
dfs: DFSCLUSTERING MATRIX=cm
clust1: CLUSTER_PROPERTIES CLUSTERS=dfs CLUSTER=1 SUM
PRINT ARG=clust1.* FILE=colvar
5.6.10
ROWSUMS
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Sum the rows of a adjacency matrix.
As discussed in the section of the manual on Exploiting contact matrices a useful tool for developing complex collective variables is the notion of the so called adjacency matrix. An adjacency matrix is an N × N matrix in which
Generated by Doxygen
342
Collective Variables
the ith, j th element tells you whether or not the ith and j th atoms/molecules from a set of N atoms/molecules
are adjacent or not. This action allows you to calculate the sum of the rows in this adjacency matrix and to then
calculate further functions of these quantities.
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
Compulsory keywords
MAT←RIX
the action that calculates the adjacency matrix vessel we would like to analyze
Options
Generated by Doxygen
5.6 Exploiting contact matrices
343
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
ALT_MIN
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
calculated using
=
The value of β in this function is specP
β
MIN
MAX
min
min
is calculated using
LESS_THAN
MORE_THAN
BETWEEN
Generated by Doxygen
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
344
Collective Variables
HISTOGRAM
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
MOMENTS
calculate the moments of the distribution of collective
variables. The mth moPN
1
m
(s
ment of a distribution is calculated using N
i=1 i − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
Examples
The first instruction in the following input file tells PLUMED to compute a 10 × 10 matrix in which the ij -element
tells you whether atoms i and j are within 1.0 nm of each other. The numbers in each of this rows are then
added together and the average value is computed. As such the following input provides an alternative method for
calculating the coordination numbers of atoms 1 to 10.
BEGIN_PLUMED_FILE
mat: CONTACT_MATRIX ATOMS=1-10 SWITCH={RATIONAL R_0=1.0}
rsums: ROWSUMS MATRIX=mat MEAN
PRINT ARG=rsums.* FILE=colvar
The following input demonstrates another way that an average coordination number can be computed. This input
calculates the number of atoms with indices between 6 and 15 that are within the first coordination spheres of each
of the atoms within indices between 1 and 5. The average coordination number is then calculated from these five
coordination numbers and this quantity is output to a file.
BEGIN_PLUMED_FILE
mat2: CONTACT_MATRIX ATOMSA=1-5 ATOMSB=6-15 SWITCH={RATIONAL R_0=1.0}
rsums: ROWSUMS MATRIX=mat2 MEAN
PRINT ARG=rsums.* FILE=colvar
5.6.11
SPRINT
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Calculate SPRINT topological variables from an adjacency matrix.
The SPRINT topological variables are calculated from the largest eigenvalue, λ of an n × n adjacency matrix and
its corresponding eigenvector, V, using:
Generated by Doxygen
5.6 Exploiting contact matrices
345
si =
√
nλvi
You can use different quantities to measure whether or not two given atoms/molecules are adjacent or not in the
adjacency matrix. The simplest measure of adjacency is is whether two atoms/molecules are within some cutoff of
each other. Further complexity can be added by insisting that two molecules are adjacent if they are within a certain
distance of each other and if they have similar orientations.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
coord
all n sprint coordinates are calculated and then stored in increasing order. the smallest sprint coordinate will be labeled label.coord-1, the second smallest will be labelled label.coord-1 and so on
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
Generated by Doxygen
346
Collective Variables
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
Compulsory keywords
MAT←RIX
the action that calculates the adjacency matrix vessel we would like to analyze
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Examples
This example input calculates the 7 SPRINT coordinates for a 7 atom cluster of Lennard-Jones atoms and prints
their values to a file. In this input the SPRINT coordinates are calculated in the manner described in ?? so two
atoms are adjacent if they are within a cutoff:
BEGIN_PLUMED_FILE
DENSITY SPECIES=1-7 LABEL=d1
CONTACT_MATRIX ATOMS=d1 SWITCH={RATIONAL R_0=0.1} LABEL=mat
SPRINT MATRIX=mat LABEL=ss
PRINT ARG=ss.* FILE=colvar
This example input calculates the 14 SPRINT coordinates for a molecule composed of 7 hydrogen and 7 carbon
atoms. Once again two atoms are adjacent if they are within a cutoff:
BEGIN_PLUMED_FILE
DENSITY SPECIES=1-7 LABEL=c
DENSITY SPECIES=8-14 LABEL=h
CONTACT_MATRIX ...
ATOMS=c,h
SWITCH11={RATIONAL R_0=2.6 NN=6 MM=12}
SWITCH12={RATIONAL R_0=2.2 NN=6 MM=12}
SWITCH22={RATIONAL R_0=2.2 NN=6 MM=12}
LABEL=mat
... CONTACT_MATRIX
SPRINT MATRIX=mat LABEL=ss
PRINT ARG=ss.* FILE=colvar
5.6.12
CLUSTER_DIAMETER
Generated by Doxygen
5.6 Exploiting contact matrices
347
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Print out the diameter of one of the connected components
As discussed in the section of the manual on Exploiting contact matrices a useful tool for developing complex collective variables is the notion of the so called adjacency matrix. An adjacency matrix is an N × N matrix in which
the ith, j th element tells you whether or not the ith and j th atoms/molecules from a set of N atoms/molecules
are adjacent or not. When analyzing these matrix we can treat them as a graph and find connected components
using some clustering algorithm. This action is used in tandem with this form of analysis to output the largest of
the distances between the pairs of atoms that are connected together in a particular connected component. It is
important to note that the quantity that is output by this action is not differentiable. As such it cannot be used as a
collective variable in a biased simulation.
Compulsory keywords
CLUSTERS
the label of the action that does the clustering
CLUSTER
( default=1 ) which cluster would you like to look at 1 is the largest cluster, 2 is the second largest,
3 is the the third largest and so on.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Examples
The following input uses PLUMED to calculate a adjacency matrix that connects a pair of atoms if they both have a
coordination number that is greater than 2.0 and if they are within 6.0 nm of each other. Depth first search clustering
is used to find the connected components in this matrix. The distance between every pair of atoms that are within
the largest of the clusters found is then calculated and the largest of these distances is output to a file named colvar.
BEGIN_PLUMED_FILE
# Calculate coordination numbers
c1: COORDINATIONNUMBER SPECIES=1-512 SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0}
# Select coordination numbers that are more than 2.0
cf: MFILTER_MORE DATA=c1 SWITCH={RATIONAL D_0=2.0 R_0=0.1} LOWMEM
# Build a contact matrix
mat: CONTACT_MATRIX ATOMS=cf SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0}
Generated by Doxygen
348
Collective Variables
# Find largest cluster
dfs: DFSCLUSTERING MATRIX=mat
clust1: CLUSTER_PROPERTIES CLUSTERS=dfs CLUSTER=1
dia: CLUSTER_DIAMETER CLUSTERS=dfs CLUSTER=1
PRINT ARG=dia FILE=colvar
5.6.13
CLUSTER_DISTRIBUTION
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Calculate functions of the distribution of properties in your connected components.
This collective variable was developed for looking at nucleation phenomena, where you are interested in using
studying the behavior of atoms in small aggregates or nuclei. In these sorts of problems you might be interested in
the distribution of the sizes of the clusters in your system. A detailed description of this CV can be found in [30].
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
Generated by Doxygen
5.6 Exploiting contact matrices
349
Compulsory keywords
CLUSTERS
the label of the action that does the clustering
TRANSFORM
( default=none ) the switching function to use to convert the crystallinity parameter to a number
between zero and one
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
( default=off ) when TRANSFORM appears alone the input symmetry functions,
x are transformed used 1 − s(x) where s(x) is a switching function. When this
option is used you instead transform using s(x) only.
INVERSE_TRANSFORM
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
BETWEEN
HISTOGRAM
ALT_MIN
Generated by Doxygen
calculate the minimum value. To make this quantity continuous the minimum
P
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
min
350
Collective Variables
MIN
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
MAX
is calculated using
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
Examples
The input provided below calculates the local q6 Steinhardt parameter on each atom. The coordination number
that atoms with a high value for the local q6 Steinhardt parameter have with other atoms that have a high value
for the local q6 Steinhardt parameter is then computed. A contact matrix is then computed that measures whether
atoms atoms i and j have a high value for this coordination number and if they are within 3.6 nm of each other. The
connected components of this matrix are then found using a depth first clustering algorithm on the corresponding
graph. The number of components in this graph that contain more than 27 atoms is then computed. As discussed
in [30] this input was used to analyze the formation of a polycrystal of GeTe from amorphous GeTe.
BEGIN_PLUMED_FILE
q6: Q6 SPECIES=1-32768 SWITCH={GAUSSIAN D_0=5.29 R_0=0.01 D_MAX=5.3} LOWMEM
lq6: LOCAL_Q6 SPECIES=q6 SWITCH={GAUSSIAN D_0=5.29 R_0=0.01 D_MAX=5.3} LOWMEM
flq6: MFILTER_MORE DATA=lq6 SWITCH={GAUSSIAN D_0=0.19 R_0=0.01 D_MAX=0.2}
cc: COORDINATIONNUMBER SPECIES=flq6 SWITCH={GAUSSIAN D_0=3.59 R_0=0.01 D_MAX=3.6}
fcc: MFILTER_MORE DATA=cc SWITCH={GAUSSIAN D_0=5.99 R_0=0.01 D_MAX=6.0}
mat: CONTACT_MATRIX ATOMS=fcc SWITCH={GAUSSIAN D_0=3.59 R_0=0.01 D_MAX=3.6}
dfs: DFSCLUSTERING MATRIX=mat
nclust: CLUSTER_DISTRIBUTION CLUSTERS=dfs TRANSFORM={GAUSSIAN D_0=5.99 R_0=0.01 D_MAX=6.0} MORE_THAN={GAUSSIAN
PRINT ARG=nclust.* FILE=colvar
5.6.14
CLUSTER_NATOMS
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Gives the number of atoms in the connected component
As discussed in the section of the manual on Exploiting contact matrices a useful tool for developing complex collective variables is the notion of the so called adjacency matrix. An adjacency matrix is an N × N matrix in which
the ith, j th element tells you whether or not the ith and j th atoms/molecules from a set of N atoms/molecules are
adjacent or not. When analyzing these matrix we can treat them as a graph and find connected components using
some clustering algorithm. This action is used in tandem with this form of analysis to output the number of atoms
that are connected together in a particular connected component. It is important to note that the quantity that is
output by this action is not differentiable. As such it cannot be used as a collective variable in a biased simulation.
Compulsory keywords
Generated by Doxygen
5.6 Exploiting contact matrices
351
CLUSTERS
the label of the action that does the clustering
CLUSTER
( default=1 ) which cluster would you like to look at 1 is the largest cluster, 2 is the second largest,
3 is the the third largest and so on.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Examples
The following input uses PLUMED to calculate a adjacency matrix that connects a pair of atoms if they both have a
coordination number that is greater than 2.0 and if they are within 6.0 nm of each other. Depth first search clustering
is used to find the connected components in this matrix and then the number of atoms in the largest cluster is found.
This quantity is then output to a file called colvar
BEGIN_PLUMED_FILE
# Calculate coordination numbers
c1: COORDINATIONNUMBER SPECIES=1-512 SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0}
# Select coordination numbers that are more than 2.0
cf: MFILTER_MORE DATA=c1 SWITCH={RATIONAL D_0=2.0 R_0=0.1} LOWMEM
# Build a contact matrix
mat: CONTACT_MATRIX ATOMS=cf SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0}
# Find largest cluster
dfs: DFSCLUSTERING MATRIX=mat
clust1: CLUSTER_PROPERTIES CLUSTERS=dfs CLUSTER=1
nat: CLUSTER_NATOMS CLUSTERS=dfs CLUSTER=1
PRINT ARG=nat FILE=COLVAR
5.6.15
CLUSTER_PROPERTIES
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Calculate properties of the distribution of some quantities that are part of a connected component
This collective variable was developed for looking at nucleation phenomena, where you are interested in using
studying the behavior of atoms in small aggregates or nuclei. In these sorts of problems you might be interested
in the degree the atoms in a nucleus have adopted their crystalline structure or (in the case of heterogeneous
nucleation of a solute from a solvent) you might be interested in how many atoms are present in the largest cluster
[30].
Generated by Doxygen
352
Collective Variables
Description of components
When the label of this action is used as the input for a second you are not referring to a scalar quantity as you are
in regular collective variables. The label is used to reference the full set of quantities calculated by the action. This
is usual when using MultiColvar functions. Generally when doing this the previously calculated multicolvar will be
referenced using the DATA keyword rather than ARG.
This Action can be used to calculate the following scalar quantities directly. These quantities are calculated by
employing the keywords listed below. These quantities can then be referenced elsewhere in the input file by using
this Action's label followed by a dot and the name of the quantity. Some of them can be calculated multiple times
with different parameters. In this case the quantities calculated can be referenced elsewhere in the input by using
the name of the quantity followed by a numerical identifier e.g. label.lessthan-1, label.lessthan-2 etc. When doing
this and, for clarity we have made it so that the user can set a particular label for each of the components. As such
by using the LABEL keyword in the description of the keyword input you can customize the component name
Quantity
Keyword
Description
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
Compulsory keywords
CLUSTERS
the label of the action that does the clustering
CLUSTER
( default=1 ) which cluster would you like to look at 1 is the largest cluster, 2 is the second largest,
3 is the the third largest and so on.
Generated by Doxygen
5.6 Exploiting contact matrices
353
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
MEAN
take the mean of these variables. The final value can be referenced using
label.mean. You can use multiple instances of this keyword i.e. MEAN1, MEA←N2, MEAN3... The corresponding values are then referenced using label.mean1, label.mean-2, label.mean-3...
MORE_THAN
calculate the number ofPvariables more than a certain target value. This quantity is calculated using i 1.0 − σ(si ), where σ(s) is a switchingfunction. The
final value can be referenced using label.morethan. You can use multiple instances of this keyword i.e. MORE_THAN1, MORE_THAN2, MORE_THA←N3... The corresponding values are then referenced using label.morethan-1,
label.morethan-2, label.morethan-3...
LESS_THAN
calculate the number ofP
variables less than a certain target value. This quantity is calculated using i σ(si ), where σ(s) is a switchingfunction. The final
value can be referenced using label.lessthan. You can use multiple instances
of this keyword i.e. LESS_THAN1, LESS_THAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1, label.lessthan-2,
label.lessthan-3...
calculate the norm of the mean vector. The final value can be referenced using
label.vmean. You can use multiple instances of this keyword i.e. VMEAN1,
VMEAN2, VMEAN3... The corresponding values are then referenced using
label.vmean-1, label.vmean-2, label.vmean-3...
VMEAN
VSUM
calculate the norm of the sum of vectors. The final value can be referenced
using label.vsum. You can use multiple instances of this keyword i.e. VSU←M1, VSUM2, VSUM3... The corresponding values are then referenced using
label.vsum-1, label.vsum-2, label.vsum-3...
BETWEEN
calculate the number of values that are within a certain range. These quantities
are calculated using kernel density estimation as described on histogrambead.
The final value can be referenced using label.between. You can use multiple instances of this keyword i.e. BETWEEN1, BETWEEN2, BETWEEN3... The corresponding values are then referenced using label.between-1, label.between-2,
label.between-3...
calculate how many of the values fall in each of the bins of a histogram.
This shortcut allows you to calculates NBIN quantities like BETWEEN. The
final value can be referenced using label.histogram. You can use multiple
instances of this keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRA←M3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
HISTOGRAM
MOMENTS
Generated by Doxygen
calculate the moments of the distribution of collective variables. The mth moPN
1
m
ment of a distribution is calculated using N
i=1 (si − s) , where s is the
average for the distribution. The moments keyword takes a lists of integers as
input or a range. Each integer is a value of m. The final calculated values can
be referenced using moment- m. You can use the COMPONENT keyword in
this action but the syntax is slightly different. If you would like the second and
third moments of the third component you would use MOMENTS={COMPO←NENT=3 MOMENTS=2-3}. The moments would then be referred to using the
labels moment-3-2 and moment-3-3. This syntax is also required if you are
using numbered MOMENT keywords i.e. MOMENTS1, MOMENTS2...
354
Collective Variables
ALT_MIN
MIN
calculate the minimum value. To make
P this quantity continuous the minimum
is calculated using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BETA= β ). The final value can be referenced using
label.altmin. You can use multiple instances of this keyword i.e. ALT_MIN1,
ALT_MIN2, ALT_MIN3... The corresponding values are then referenced using
label.altmin-1, label.altmin-2, label.altmin-3...
calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β
min
min
log
i
exp
si
ified using (BETA= β ) The final value can be referenced using label.min. You
can use multiple instances of this keyword i.e. MIN1, MIN2, MIN3... The corresponding values are then referenced using label.min-1, label.min-2, label.min3...
calculate the maximum value. To make this
continuous the maximum
quantity
MAX
is calculated using
max = β log
P
i
exp
si
β
The value of β in this function is
specified using (BETA= β ) The final value can be referenced using label.max.
You can use multiple instances of this keyword i.e. MAX1, MAX2, MAX3...
The corresponding values are then referenced using label.max-1, label.max-2,
label.max-3...
calculate the sum of all the quantities. The final value can be referenced using
label.sum. You can use multiple instances of this keyword i.e. SUM1, SU←M2, SUM3... The corresponding values are then referenced using label.sum-1,
label.sum-2, label.sum-3...
SUM
LOWEST
this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
HIGHEST
this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest
Examples
The input below calculates the coordination numbers of atoms 1-100 and then computes the an adjacency matrix
whose elements measures whether atoms i and j are within 0.55 nm of each other. The action labelled dfs then
treats the elements of this matrix as zero or ones and thus thinks of the matrix as defining a graph. This dfs action
then finds the largest connected component in this graph. The sum of the coordination numbers for the atoms in
this largest connected component are then computed and this quantity is output to a colvar file. The way this input
can be used is described in detail in [30].
BEGIN_PLUMED_FILE
lq: COORDINATIONNUMBER SPECIES=1-100 SWITCH={CUBIC D_0=0.45 D_MAX=0.55} LOWMEM
cm: CONTACT_MATRIX ATOMS=lq SWITCH={CUBIC D_0=0.45 D_MAX=0.55}
dfs: DFSCLUSTERING MATRIX=cm
clust1: CLUSTER_PROPERTIES CLUSTERS=dfs CLUSTER=1 SUM
PRINT ARG=clust1.* FILE=colvar
5.6.16
DUMPGRAPH
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Generated by Doxygen
5.6 Exploiting contact matrices
355
Write out the connectivity of the nodes in the graph in dot format.
Compulsory keywords
MATRIX
the action that calculates the adjacency matrix vessel we would like to analyze
STRIDE
( default=1 ) the frequency with which you would like to output the graph
FILE
the name of the file on which to output the data
MAXCONNECT
( default=0 ) maximum number of connections that can be formed by any given node in the
graph. By default this is set equal to zero and the number of connections is set equal to the
number of nodes. You only really need to set this if you are working with a very large system
and memory is at a premium
Examples
5.6.17
OUTPUT_CLUSTER
This is part of the adjmat module
It is only available if you configure PLUMED with ./configure –enable-modules=adjmat . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Output the indices of the atoms in one of the clusters identified by a clustering object
This action provides one way of getting output from a DFSCLUSTERING calculation. The output in question here
is either
• a file that contains a list of the atom indices that form part of one of the clusters that was identified using
DFSCLUSTERING
• an xyz file containing the positions of the atoms in one of the the clusters that was identified using
DFSCLUSTERING
Notice also that if you choose to output an xyz file you can ask PLUMED to try to reconstruct the cluster taking the
periodic boundary conditions into account by using the MAKE_WHOLE flag.
Compulsory keywords
CLUSTERS
the action that performed the clustering
CLUSTER
( default=1 ) which cluster would you like to look at 1 is the largest cluster, 2 is the second largest,
3 is the the third largest and so on
STRIDE
( default=1 ) the frequency with which you would like to output the atoms in the cluster
FILE
the name of the file on which to output the details of the cluster
MAXDEPTH
( default=6 ) maximum depth for searches over paths to reconstruct clusters for PBC
MAXGOES
( default=200 ) number of times to run searches to reconstruct clusters
Generated by Doxygen
356
Collective Variables
Options
MAKE_WHOLE
( default=off ) reconstruct the clusters and remove all periodic boundary conditions.
Examples
The input shown below identifies those atoms with a coordination number less than 13 and then constructs a contact
matrix that describes the connectivity between the atoms that satisfy this criteria. The DFS algorithm is then used
to find the connected components in this matrix and the indices of the atoms in the largest connected component
are then output to a file.
BEGIN_PLUMED_FILE
c1: COORDINATIONNUMBER SPECIES=1-1996 SWITCH={CUBIC D_0=0.34 D_MAX=0.38}
cf: MFILTER_LESS DATA=c1 SWITCH={CUBIC D_0=13 D_MAX=13.5}
mat: CONTACT_MATRIX ATOMS=cf SWITCH={CUBIC D_0=0.34 D_MAX=0.38}
dfs: DFSCLUSTERING MATRIX=mat
OUTPUT_CLUSTER CLUSTERS=dfs CLUSTER=1 FILE=dfs.dat
Generated by Doxygen
Chapter 6
Analysis
PLUMED can be used to analyze trajectories either on the fly during an MD run or via post processing a trajectory using driver. A molecular dynamics trajectory is in essence an ordered set of configurations of atoms.
Trajectory analysis algorithms are methods that allow us to extract meaningful information from this extremely highdimensionality information. In extracting this information much of the information in the trajectory will be discarded
and assumed to be irrelevant to the problem at hand. For example, when we calculate a histogram from a trajectory
we throw away all information on the order the frames were visited during the trajectory. We instead opt to display
a time average that shows the parts of configuration space that were
visited most frequently. There are many situations in which this is a reasonable thing to do as we know that time
averages are equivalent to ensemble averages in the long timescale limit and that these average probabilities of
being in different parts of configuration space, P (s), are thus related to the underlying free energy, F (s), via:
F (s) = −kB T ln P (s)
About the simplest form of analysis that PLUMED can perform involves printing information to a file. PLUMED can
output various different kinds of information to files as described below:
COMMITTOR
Does a committor analysis.
DUMPATOMS
Dump selected atoms on a file.
DUMPDERIVATIVES
Dump the derivatives with respect to the input parameters for one or more objects
(generally CVs, functions or biases).
DUMPFORCES
Dump the force acting on one of a values in a file.
DUMPMASSCHARGE
Dump masses and charges on a selected file.
DUMPMULTICOLVAR
Dump atom positions and multicolvar on a file.
DUMPPROJECTIONS
Dump the derivatives with respect to the input parameters for one or more objects
(generally CVs, functions or biases).
PRINT
Print quantities to a file.
UPDATE_IF
Conditional update of other actions.
The UPDATE_IF action allows you to do more complex things using the above print commands. As detailed in the
documentation for UPDATE_IF when you put any of the above actions within an UPDATE_IF block then data will
only be output to the file if colvars are within particular ranges. In other words, the above printing commands, in
tandem with UPDATE_IF, allow you to identify the frames in your trajectory that satisfy some particular criteria and
output information on those frames only.
Another useful command is the COMMITTOR command. As detailed in the documentation for COMMITTOR this
command tells PLUMED (and the underlying MD code) to stop the calculation one some criteria is satisfied, alternatively one can use it to keep track of the number of times a criteria is satisfied.
358
Analysis
A number of more complicated forms of analysis can be performed that take a number of frames from the trajectory
as input. In all these commands the STRIDE keyword is used to tell PLUMED how frequently to collect data from the
trajectory. In all these methods the output from the analysis is a form of ensemble average. If you are running with
a bias it is thus likely that you may want to reweight the trajectory frames in order to remove the effect the bias has
on the static behavior of the system. The following methods can thus be used to calculate weights for the various
trajectory frames so that the final ensemble average is an average for the canonical ensemble at the appropriate
temperature.
6.1
Reweighting and Averaging
REWEIGHT_BIAS
Calculate weights for ensemble averages that negate the effect the bias has on the
region of phase space explored
REWEIGHT_METAD
Calculate the weights configurations should contribute to the histogram in a simulation
in which a metadynamics bias acts upon the system.
REWEIGHT_TEMP
Calculate weights for ensemble averages allow for the computing of ensemble averages
at temperatures lower/higher than that used in your original simulation.
REWEIGHT_WHAM
WHAM_HISTOGRAM
This can be used to output the a histogram using the weighted histogram technique
WHAM_WEIGHTS
This can be used to output the data that has been stored in an Analysis object.
You can then calculate ensemble averages using the following actions.
AVERAGE
Calculate the ensemble average of a collective variable
HISTOGRAM
Accumulate the average probability density along a few CVs from a trajectory.
MULTICOLVARDENS
Evaluate the average value of a multicolvar on a grid.
For many of the above commands data is accumulated on the grids. These grids can be further analyzed using one
of the actions detailed below at some time.
CONVERT_TO_FES
Convert a histogram, H(x), to a free energy surface using F (x) =
−kB T ln H(x).
DUMPCUBE
Output a three dimensional grid using the Gaussian cube file format.
DUMPGRID
Output the function on the grid to a file with the PLUMED grid format.
FIND_CONTOUR_SURFACE
Find an isocontour by searching along either the x, y or z direction.
FIND_CONTOUR
FIND_SPHERICAL_CONTOUR
Find an isocontour in a smooth function.
Find an isocontour in a three dimensional grid by searching over a Fibonacci
sphere.
FOURIER_TRANSFORM
Compute the Discrete Fourier Transform (DFT) by means of FFTW of data
stored on a 2D grid.
GRID_TO_XYZ
Output the function on the grid to an xyz file
INTEGRATE_GRID
Calculate the total integral of the function on the input grid
INTERPOLATE_GRID
Interpolate a smooth function stored on a grid onto a grid with a smaller grid
spacing.
As an example the following set of commands instructs PLUMED to calculate the distance between atoms 1 and 2
for every fifth frame in the trajectory and to accumulate a histogram from this data which will be output every 100
steps (i.e. when 20 distances have been added to the histogram).
Generated by Doxygen
6.2 Diagnostic tools
359
BEGIN_PLUMED_FILE
x: DISTANCE ATOMS=1,2
h: HISTOGRAM ARG=x GRID_MIN=0.0 GRID_MAX=3.0 GRID_BIN=100 BANDWIDTH=0.1 STRIDE=5
DUMPGRID GRID=h FILE=histo STRIDE=100
It is important to note when using commands such as the above the first frame in the trajectory is assumed to be
the initial configuration that was input to the MD code. It is thus ignored. Furthermore, if you are running with driver
and you would like to analyze the whole trajectory (without specifying its length) and then print the result you simply
call DUMPGRID (or any of the commands above) without a STRIDE keyword as shown in the example below.
BEGIN_PLUMED_FILE
x: DISTANCE ATOMS=1,2
h: HISTOGRAM ARG=x GRID_MIN=0.0 GRID_MAX=3.0 GRID_BIN=100 BANDWIDTH=0.1 STRIDE=5
DUMPGRID GRID=h FILE=histo
Please note that even with this calculation the first frame in the trajectory is ignored when computing the histogram.
Notice that all the commands for calculating smooth functions described above calculate some sort of average.
There are two ways that you may wish to average the data in your trajectory:
• You might want to calculate block averages in which the first N N frames in your trajectory are averaged
separately to the second block of N frames. If this is the case you should use the keyword CLEAR in the
input to the action that calculates the smooth function. This keyword is used to specify how frequently you
are clearing the stored data.
• You might want to calculate an accumulate an average over the whole trajectory and output the average
accumulated at step N , step 2N ... This is what PLUMED does by default so you do not need to use CLEAR
in this case.
6.2
Diagnostic tools
PLUMED has a number of diagnostic tools that can be used to check that new Actions are working correctly:
DUMPFORCES
Dump the force acting on one of a values in a file.
DUMPDERIVATIVES
Dump the derivatives with respect to the input parameters for one or more objects
(generally CVs, functions or biases).
DUMPMASSCHARGE
Dump masses and charges on a selected file.
DUMPPROJECTIONS
Dump the derivatives with respect to the input parameters for one or more objects
(generally CVs, functions or biases).
These commands allow you to test that derivatives and forces are calculated correctly within colvars and functions.
One place where this is very useful is when you are testing whether or not you have implemented the derivatives
of a new collective variables correctly. So for example if we wanted to do such a test on the distance CV we would
employ an input file something like this:
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=1,2
d1n: DISTANCE ATOMS=1,2 NUMERICAL_DERIVATIVES
DUMPDERIVATIVES ARG=d1,d1n FILE=derivatives
The first of these two distance commands calculates the analytical derivatives of the distance while the second
calculates these derivatives numerically. Obviously, if your CV is implemented correctly these two sets of quantities
should be nearly identical.
Generated by Doxygen
360
6.3
Analysis
Storing data for analysis
All the analysis methods described in previous sections accumulate averages or output diagnostic information on
the fly. That is to say these methods calculate something given the instantaneous positions of the atoms or the
instantaneous values of a set of collective variables. Many methods (e.g. dimensionality reduction and clustering)
will not work like this, however, as information from multiple trajectory frames is required at the point when the
analysis is performed. In other words the output from these types of analysis cannot be accumulated one frame
at time. When using these methods you must therefore store trajectory frames for later analysis. You can do this
storing by using the following action:
COLLECT_FRAMES
6.4
Collect and store trajectory frames for later analysis with one of the methods detailed
below.
Calculating dissimilarity matrices
One of the simplest things that we can do if we have stored a set of trajectory frames using COLLECT_FRAMES
is we can calculate the dissimilarity between every pair of frames we have stored.
When using the
dimensionality reduction algorithms described in the sections that follow the first step is to calculate this matrix. Consequently, within PLUMED the following command will collect the trajectory data as your simulation
progressed and calculate the dissimilarities:
EUCLIDEAN_DISSIMILARITIES
Calculate the matrix of dissimilarities between a trajectory of atomic configurations.
By exploiting the functionality described in Distances from reference configurations you can calculate these dissimilarities in a wide variety of different ways (e.g. you can use RMSD, or you can use a collection of collective variable
values see TARGET). If you wish to view this dissimilarity information you can print these quantities to a file using:
PRINT_DISSIMILARITY_MATRIX
Print the matrix of dissimilarities between a trajectory of atomic configurations.
In addition, if PLUMED does not calculate the dissimilarities you need you can read this information from an external
file
READ_DISSIMILARITY_MATRIX
Read a matrix of dissimilarities between a trajectory of atomic configurations from a file.
N.B. You can only use the two commands above when you are doing post-processing.
6.5
Landmark Selection
Many of the techniques described in the following sections are very computationally expensive to run on large
trajectories. A common strategy is thus to use a landmark selection algorithm to pick a particularly-representative
subset of trajectory frames and to only apply the expensive analysis algorithm on these configurations. The various
landmark selection algorithms that are available in PLUMED are as follows
Generated by Doxygen
6.6 Dimensionality Reduction
361
LANDMARK_SELECT_FPS
Select a set of landmarks using farthest point sampling.
LANDMARK_SELECT_RANDOM
Select a random set of landmarks from a large set of configurations.
LANDMARK_SELECT_STAGED
Select a set of landmarks using the staged algorithm.
LANDMARK_SELECT_STRIDE
Select every k th landmark from the trajectory.
RESELECT_LANDMARKS
This allows us to use one measure in landmark selection and a different
measure in dimensionality reduction
In general most of these landmark selection algorithms must be used in tandem with a dissimilarity matrix object as
as follows:
BEGIN_PLUMED_FILE
data: COLLECT_FRAMES ARG=d1 STRIDE=1
ss1: EUCLIDEAN_DISSIMILARITIES USE_OUTPUT_DATA_FROM=data
ll2: LANDMARK_SELECT_FPS USE_OUTPUT_DATA_FROM=ss1 NLANDMARKS=300
OUTPUT_COLVAR_FILE USE_OUTPUT_DATA_FROM=ll2 FILE=mylandmarks
When landmark selection is performed in this way a weight is ascribed to each of the landmark configurations. This
weight is calculated by summing the weights of all the trajectory frames in each of the landmarks Voronoi polyhedron
(https://en.wikipedia.org/wiki/Voronoi_diagram). The weight of each trajectory frame is one
unless you are reweighting using the formula described in the Reweighting and Averaging to counteract the fact of
a simulation bias or an elevated temperature. If you are reweighting using these formula the weight of each of the
points is equal to the exponential term in the numerator of these expressions.
6.6
Dimensionality Reduction
Many dimensionality reduction algorithms work in a manner similar to the way we use when we make maps. You
start with distances between London, Belfast, Paris and Dublin and then you try to arrange points on a piece of
paper so that the (suitably transformed) distances between the points in your map representing each of those cities
are related to the true distances between the cities.
Stating this more mathematically MDS endeavors to find an isometry between points distributed in a highdimensional space and a set of points distributed in a low-dimensional plane.
In other words, if we have M D -dimensional points, X, and we can calculate dissimilarities between pairs them,
Dij , we can, with an MDS calculation, try to create M projections, x, of the high dimensionality points in a ddimensional linear space by trying to arrange the projections so that the Euclidean distances between pairs of
them, dij , resemble the dissimilarities between the high dimensional points. In short we minimize:
χ2 =
X
2
wi wj (F (Dij ) − f (dij ))
i6=j
where F (Dij ) is some transformation of the distance between point X i and point X j and f (dij ) is some transformation of the distance between the projection of X i , xi , and the projection of X j , xj . wi and wj are the weights of
configurations X i and j respectively. These weights are calculated using the reweighting and Voronoi polyhedron
approaches described in previous sections. A tutorial on dimensionality reduction and how it can be used to analyze
simulations can be found in the tutorial Belfast tutorial: Adaptive variables II and in the following short video.
Within PLUMED running an input to run a dimensionality reduction algorithm can be as simple as:
BEGIN_PLUMED_FILE
data: COLLECT_FRAMES STRIDE=1 ARG=d1
ss1: EUCLIDEAN_DISSIMILARITIES USE_OUTPUT_DATA_FROM=data
mds: CLASSICAL_MDS USE_OUTPUT_DATA_FROM=ss1 NLOW_DIM=2
Generated by Doxygen
362
Analysis
Where we have to use the EUCLIDEAN_DISSIMILARITIES action here in order to calculate the matrix of dissimilarities between trajectory frames. We can even throw some landmark selection into this procedure and perform
BEGIN_PLUMED_FILE
data: COLLECT_FRAMES STRIDE=1 ARG=d1
matrix: EUCLIDEAN_DISSIMILARITIES USE_OUTPUT_DATA_FROM=data
ll2: LANDMARK_SELECT_FPS USE_OUTPUT_DATA_FROM=matrix NLANDMARKS=300
mds: CLASSICAL_MDS USE_OUTPUT_DATA_FROM=ll2 NLOW_DIM=2
osample: PROJECT_ALL_ANALYSIS_DATA USE_OUTPUT_DATA_FROM=matrix PROJECTION=smap
Notice here that the final command allows us to calculate the projections of all the non-landmark points that were
collected by the action with label matrix.
Dimensionality can be more complicated, however, because the stress function that calculates χ2 has to optimized
rather carefully using a number of different algorithms. The various algorithms that can be used to optimize this
function are described below
CLASSICAL_MDS
Create a low-dimensional projection of a trajectory using the classical multidimensional scaling algorithm.
OUTPUT_PCA_PROJECTION
This is used to output the projection calculated by principle component
analysis
PCA
Perform principal component analysis (PCA) using either the positions of
the atoms a large number of collective variables as input.
PROJECT_ALL_ANALYSIS_DATA
Find projections of all non-landmark points using the embedding calculated by a dimensionality reduction optimization calculation.
SKETCHMAP_CONJGRAD
Optimize the sketch-map stress function using conjugate gradients.
SKETCHMAP_POINTWISE
Optimize the sketch-map stress function using a pointwise global optimization algorithm.
SKETCHMAP_READ
Read in a sketch-map projection from an input file
SKETCHMAP_SMACOF
Optimize the sketch-map stress function using the SMACOF algorithm.
SKETCH_MAP
This can be used to output the data that has been stored in an Analysis
object.
SMACOF_MDS
Optimize the multidimensional scaling stress function using the SMACOF
algorithm.
6.7
Outputting the results from analysis algorithms
The following methods are available for printing the result output by the various analysis algorithms:
OUTPUT_ANALYSIS_DATA_TO_COLVAR
OUTPUT_ANALYSIS_DATA_TO_PDB
Output the results from an analysis using the PLUMED colvar file
format.
Output the results from an analysis using the PDB file format.
Using the above commands to output the data from any form of analysis is important as the STRIDE with which
you output the data to a COLVAR or PDB file controls how frequently the analysis is performed on the
collected data . If you specified no stride on the output lines then PLUMED assumes you want to perform analysis
on the entire trajectory.
If you use the above commands to output data from one of the Landmark Selection algorithms then only the
second will give you information on the atomic positions in your landmark configurations and their associated weights. The first of these commands will give the values of the colvars in the landmark configurations
only. If you use the above commands to output data from one of the Dimensionality Reduction algorithms then
Generated by Doxygen
6.8 COMMITTOR
363
OUTPUT_ANALYSIS_DATA_TO_COLVAR will give you an output file that contains the projection for each of your
input points. OUTPUT_ANALYSIS_DATA_TO_PDB will give you a PDB that contains the position of the input point,
the projections and the weight of the configuration.
A nice feature of plumed is that when you use Landmark Selection algorithms or Dimensionality Reduction algorithms the output information is just a vector of variables. As such you can use HISTOGRAM to construct a histogram
of the information generated by these algorithms.
6.8
COMMITTOR
This is part of the analysis module
Does a committor analysis.
Compulsory keywords
BASIN_LL
List of lower limits for basin # You can use multiple instances of this keyword i.e. BASIN_LL1,
BASIN_LL2, BASIN_LL3...
BASIN_UL
List of upper limits for basin # You can use multiple instances of this keyword i.e. BASIN_UL1,
BASIN_UL2, BASIN_UL3...
STRIDE
( default=1 ) the frequency with which the CVs are analyzed
Options
NOSTOP
( default=off ) if true do not stop the simulation when reaching a basin but just keep track of it
ARG
the input for this action is the scalar output from one or more other actions. The particular scalars
that you will use are referenced using the label of the action. If the label appears on its own then it
is assumed that the Action calculates a single scalar value. The value of this scalar is thus used as
the input to this new action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and each component of
the output has a specific label. For example a DISTANCE action labelled dist may have three
components x, y and z. To take just the x component you should use dist.x, if you wish to take all
three components then use dist.∗.More information on the referencing of Actions can be found in
the section of the manual on the PLUMED Getting Started. Scalar values can also be referenced
using POSIX regular expressions as detailed in the section on Regular Expressions. To use this
feature you you must compile PLUMED with the appropriate flag. You can use multiple instances of
this keyword i.e. ARG1, ARG2, ARG3...
FILE
the name of the file on which to output the reached basin
FMT
the format that should be used to output real numbers
Examples
The following input monitors two torsional angles during a simulation, defines two basins (A and B) as a function of
the two torsion angles and stops the simulation when it falls in one of the two. In the log file will be shown the latest
values for the CVs and the basin reached.
Generated by Doxygen
364
Analysis
BEGIN_PLUMED_FILE
TORSION ATOMS=1,2,3,4 LABEL=r1
TORSION ATOMS=2,3,4,5 LABEL=r2
COMMITTOR ...
ARG=r1,r2
STRIDE=10
BASIN_LL1=0.15,0.20
BASIN_UL1=0.25,0.40
BASIN_LL2=-0.25,-0.40
BASIN_UL2=-0.15,-0.20
... COMMITTOR
6.9
DUMPATOMS
This is part of the generic module
Dump selected atoms on a file.
This command can be used to output the positions of a particular set of atoms. The atoms required are output
in a xyz or gro formatted file. If PLUMED has been compiled with xdrfile support, then also xtc and trr files can
be written. To this aim one should install xdrfile library (http://www.gromacs.org/Developer_Zone/←Programming_Guide/XTC_Library). If the xdrfile library is installed properly the PLUMED configure script
should be able to detect it and enable it. The type of file is automatically detected from the file extension, but
can be also enforced with TYPE. Importantly, if your input file contains actions that edit the atoms position (e.←g. WHOLEMOLECULES) and the DUMPATOMS command appears after this instruction, then the edited atom
positions are output. You can control the buffering of output using the FLUSH keyword on a separate line.
Units of the printed file can be controlled with the UNITS keyword. By default PLUMED units as controlled in the
UNITS command are used, but one can override it e.g. with UNITS=A. Notice that gro/xtc/trr files can only contain
coordinates in nm.
The atoms involved can be specified using
ATOMS
the atom indices whose positions you would like to print out. For more information on how to specify
lists of atoms see Groups and Virtual Atoms
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the atoms should be output
FILE
file on which to output coordinates; extension is automatically detected
UNITS
( default=PLUMED ) the units in which to print out the coordinates. PLUMED means internal PLU←MED units
Options
PRECISION
The number of digits in trajectory file
TYPE
file type, either xyz, gro, xtc, or trr, can override an automatically detected file extension
Generated by Doxygen
6.10 DUMPDERIVATIVES
RESTART
allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM
Only update this action from this time
UPDATE_UN←TIL
Only update this action until this time
365
Examples
The following input instructs plumed to print out the positions of atoms 1-10 together with the position of the center
of mass of atoms 11-20 every 10 steps to a file called file.xyz.
BEGIN_PLUMED_FILE
COM ATOMS=11-20 LABEL=c1
DUMPATOMS STRIDE=10 FILE=file.xyz ATOMS=1-10,c1
Notice that the coordinates in the xyz file will be expressed in nm, since these are the defaults units in PLUMED. If
you want the xyz file to be expressed in A, you should use the following input
BEGIN_PLUMED_FILE
COM ATOMS=11-20 LABEL=c1
DUMPATOMS STRIDE=10 FILE=file.xyz ATOMS=1-10,c1 UNITS=A
As an alternative, you might want to set all the length used by PLUMED to Angstrom using the UNITS action.
However, this latter choice will affect all your input and output.
The following input is very similar but dumps a .gro (gromacs) file, which also contains atom and residue names.
BEGIN_PLUMED_FILE
# this is required to have proper atom names:
MOLINFO STRUCTURE=reference.pdb
# if omitted, atoms will have "X" name...
COM ATOMS=11-20 LABEL=c1
DUMPATOMS STRIDE=10 FILE=file.gro ATOMS=1-10,c1
# notice that last atom is a virtual one and will not have
# a correct name in the resulting gro file
The file.gro will contain coordinates expressed in nm, since this is the convention for gro files.
In case you have compiled PLUMED with xdrfile library, you might even write xtc or trr files as follows
BEGIN_PLUMED_FILE
COM ATOMS=11-20 LABEL=c1
DUMPATOMS STRIDE=10 FILE=file.xtc ATOMS=1-10,c1
Notice that xtc files are significantly smaller than gro and xyz files.
Finally, consider that gro and xtc file store coordinates with limited precision set by the PRECISION keyword.
Default value is 3, which means "3 digits after dot" in nm (1/1000 of a nm). The following will write a larger xtc file
with high resolution coordinates:
BEGIN_PLUMED_FILE
COM ATOMS=11-20 LABEL=c1
DUMPATOMS STRIDE=10 FILE=file.xtc ATOMS=1-10,c1 PRECISION=7
6.10
DUMPDERIVATIVES
Generated by Doxygen
366
Analysis
This is part of the generic module
Dump the derivatives with respect to the input parameters for one or more objects (generally CVs, functions or
biases).
For a CV this line in input instructs plumed to print the derivative of the CV with respect to the atom positions and
the cell vectors (virial-like form). In contrast, for a function or bias the derivative with respect to the input "CVs" will
be output. This command is most often used to test whether or not analytic derivatives have been implemented
correctly. This can be done by outputting the derivatives calculated analytically and numerically. You can control the
buffering of output using the FLUSH keyword.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the derivatives should be output
FILE
the name of the file on which to output the derivatives
FMT
( default=%15.10f ) the format with which the derivatives should be output
Options
ARG
the input for this action is the scalar output from one or more other actions. The particular
scalars that you will use are referenced using the label of the action. If the label appears on
its own then it is assumed that the Action calculates a single scalar value. The value of this
scalar is thus used as the input to this new action. If ∗ or ∗.∗ appears the scalars calculated
by all the proceeding actions in the input file are taken. Some actions have multi-component
outputs and each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x component you
should use dist.x, if you wish to take all three components then use dist.∗.More information
on the referencing of Actions can be found in the section of the manual on the PLUMED
Getting Started. Scalar values can also be referenced using POSIX regular expressions as
detailed in the section on Regular Expressions. To use this feature you you must compile
PLUMED with the appropriate flag. You can use multiple instances of this keyword i.e. A←RG1, ARG2, ARG3...
RESTART
allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM
Only update this action from this time
UPDATE_UN←TIL
Only update this action until this time
Examples
The following input instructs plumed to write a file called deriv that contains both the analytical and numerical
derivatives of the distance between atoms 1 and 2.
BEGIN_PLUMED_FILE
DISTANCE ATOM=1,2 LABEL=distance
DISTANCE ATOM=1,2 LABEL=distanceN NUMERICAL_DERIVATIVES
DUMPDERIVATIVES ARG=distance,distanceN STRIDE=1 FILE=deriv
(See also DISTANCE)
Generated by Doxygen
6.11 DUMPFORCES
6.11
367
DUMPFORCES
This is part of the generic module
Dump the force acting on one of a values in a file.
For a CV this command will dump the force on the CV itself. Be aware that in order to have the forces on the atoms
you should multiply the output from this argument by the output from DUMPDERIVATIVES. Furthermore, also note
that you can output the forces on multiple quantities simultaneously by specifying more than one argument. You can
control the buffering of output using the FLUSH keyword.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the forces should be output
FILE
the name of the file on which to output the forces
FMT
( default=%15.10f ) the format with which the derivatives should be output
Options
ARG
the input for this action is the scalar output from one or more other actions. The particular
scalars that you will use are referenced using the label of the action. If the label appears on
its own then it is assumed that the Action calculates a single scalar value. The value of this
scalar is thus used as the input to this new action. If ∗ or ∗.∗ appears the scalars calculated
by all the proceeding actions in the input file are taken. Some actions have multi-component
outputs and each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x component you
should use dist.x, if you wish to take all three components then use dist.∗.More information
on the referencing of Actions can be found in the section of the manual on the PLUMED
Getting Started. Scalar values can also be referenced using POSIX regular expressions as
detailed in the section on Regular Expressions. To use this feature you you must compile
PLUMED with the appropriate flag. You can use multiple instances of this keyword i.e. A←RG1, ARG2, ARG3...
RESTART
allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM
Only update this action from this time
UPDATE_UN←TIL
Only update this action until this time
Examples
The following input instructs plumed to write a file called forces that contains the force acting on the distance between
atoms 1 and 2.
BEGIN_PLUMED_FILE
DISTANCE ATOM=1,2 LABEL=distance
DUMPFORCES ARG=distance STRIDE=1 FILE=forces
Generated by Doxygen
368
6.12
Analysis
DUMPMASSCHARGE
Generated by Doxygen
6.12 DUMPMASSCHARGE
369
This is part of the generic module
Dump masses and charges on a selected file.
This command dumps a file containing charges and masses. It does so only once in the simulation (at first step).
File can be recycled in the driver tool.
Notice that masses and charges are only written once at the beginning of the simulation. In case no atom list is
provided, charges and masses for all atoms are written.
The atoms involved can be specified using
ATOMS
the atom indices whose charges and masses you would like to print out. For more information on
how to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the atoms should be output
FILE
file on which to output charges and masses.
Options
ONLY_MASSES
( default=off ) Only output masses to file
ONLY_CHARGES
( default=off ) Only output charges to file
Examples
You can add the DUMPMASSCHARGE action at the end of the plumed.dat file that you use during an MD
simulations:
BEGIN_PLUMED_FILE
c1: COM ATOMS=1-10
c2: COM ATOMS=11-20
PRINT ARG=c1,c2 FILE=colvar STRIDE=100
DUMPMASSCHARGE FILE=mcfile
In this way, you will be able to use the same masses while processing a trajectory from the driver . To do so, you
need to add the –mc flag on the driver command line, e.g.
plumed driver --mc mcfile --plumed plumed.dat --ixyz traj.xyz
Generated by Doxygen
370
Analysis
With the following input you can dump only the charges for a specific group.
BEGIN_PLUMED_FILE
solute_ions: GROUP ATOMS=1-121,200-2012
DUMPATOMS FILE=traj.gro ATOMS=solute_ions STRIDE=100
DUMPMASSCHARGE FILE=mcfile ATOMS=solute_ions
Notice however that if you want to process the charges with the driver (e.g. reading traj.gro) you have to fix atom
numbers first, e.g. with the script
awk ’BEGIN{c=0}{
if(match($0,"#")) print ; else {print c,$2,$3; c++}
}’ < mc > newmc
}’
then
plumed driver --mc newmc --plumed plumed.dat --ixyz traj.gro
6.13
DUMPMULTICOLVAR
This is part of the multicolvar module
Dump atom positions and multicolvar on a file.
The atoms involved can be specified using
ORIGIN
You can use this keyword to specify the position of an atom as an origin. The positions output will
then be displayed relative to that origin. For more information on how to specify lists of atoms see
Groups and Virtual Atoms
Compulsory keywords
DATA
certain actions in plumed work by calculating a list of variables and summing over them. This particular action can be used to calculate functions of these base variables or prints them to a file. This
keyword thus takes the label of one of those such variables as input.
STRIDE
( default=1 ) the frequency with which the atoms should be output
FILE
file on which to output coordinates
UNITS
( default=PLUMED ) the units in which to print out the coordinates. PLUMED means internal PLU←MED units
Options
PRECISION
The number of digits in trajectory file
Generated by Doxygen
6.14 DUMPPROJECTIONS
371
Examples
In this examples we calculate the distances between the atoms of the first and the second group and we write them
in the file MULTICOLVAR.xyz. For each couple it writes the coordinates of their geometric center and their distance.
BEGIN_PLUMED_FILE
pos:
GROUP ATOMS=220,221,235,236,247,248,438,439,450,451,534,535
neg:
GROUP ATOMS=65,68,138,182,185,267,270,291,313,316,489,583,621,711
DISTANCES GROUPA=pos GROUPB=neg LABEL=slt
DUMPMULTICOLVAR DATA=slt FILE=MULTICOLVAR.xyz
(see also DISTANCES)
6.14
DUMPPROJECTIONS
This is part of the generic module
Dump the derivatives with respect to the input parameters for one or more objects (generally CVs, functions or
biases).
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the derivatives should be output
FILE
the name of the file on which to output the derivatives
FMT
( default=%15.10f ) the format with which the derivatives should be output
Options
ARG
the input for this action is the scalar output from one or more other actions. The particular
scalars that you will use are referenced using the label of the action. If the label appears on
its own then it is assumed that the Action calculates a single scalar value. The value of this
scalar is thus used as the input to this new action. If ∗ or ∗.∗ appears the scalars calculated
by all the proceeding actions in the input file are taken. Some actions have multi-component
outputs and each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x component you
should use dist.x, if you wish to take all three components then use dist.∗.More information
on the referencing of Actions can be found in the section of the manual on the PLUMED
Getting Started. Scalar values can also be referenced using POSIX regular expressions as
detailed in the section on Regular Expressions. To use this feature you you must compile
PLUMED with the appropriate flag. You can use multiple instances of this keyword i.e. A←RG1, ARG2, ARG3...
RESTART
allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM
Only update this action from this time
UPDATE_UN←TIL
Only update this action until this time
Generated by Doxygen
372
Analysis
Examples
Compute the distance between two groups and write on a file the derivatives of this distance with respect to all the
atoms of the two groups
BEGIN_PLUMED_FILE
x1: CENTER ATOMS=1-10
x2: CENTER ATOMS=11-20
d: DISTANCE ATOMS=x1,x2
DUMPPROJECTIONS ARG=d FILE=proj STRIDE=20
6.15
PRINT
This is part of the generic module
Print quantities to a file.
This directive can be used multiple times in the input so you can print files with different strides or print different
quantities to different files. You can control the buffering of output using the FLUSH keyword. Output file is either
appended or backed up depending on the presence of the RESTART action. A per-action RESTART keyword can
be used as well.
Notice that printing happens in the so-called "update" phase. This implies that printing is affected by the presence
of UPDATE_IF actions. In addition, one might decide to start and stop printing at preassigned values of time using
the UPDATE_FROM and UPDATE_UNTIL keywords. Keep into account that even on steps when the action is not
updated (and thus the file is not printed) the argument will be activated. In other words, if you use UPDATE_FROM
to start printing at a given time, the collective variables this PRINT statement depends on will be computed also
before that time.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the quantities of interest should be output
Options
ARG
the input for this action is the scalar output from one or more other actions. The particular
scalars that you will use are referenced using the label of the action. If the label appears on
its own then it is assumed that the Action calculates a single scalar value. The value of this
scalar is thus used as the input to this new action. If ∗ or ∗.∗ appears the scalars calculated
by all the proceeding actions in the input file are taken. Some actions have multi-component
outputs and each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x component you
should use dist.x, if you wish to take all three components then use dist.∗.More information
on the referencing of Actions can be found in the section of the manual on the PLUMED
Getting Started. Scalar values can also be referenced using POSIX regular expressions as
detailed in the section on Regular Expressions. To use this feature you you must compile
PLUMED with the appropriate flag. You can use multiple instances of this keyword i.e. A←RG1, ARG2, ARG3...
Generated by Doxygen
6.15 PRINT
373
FILE
the name of the file on which to output these quantities
FMT
the format that should be used to output real numbers
RESTART
allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM
Only update this action from this time
UPDATE_UN←TIL
Only update this action until this time
Examples
The following input instructs plumed to print the distance between atoms 3 and 5 on a file called COLVAR every 10
steps, and the distance and total energy on a file called COLVAR_ALL every 1000 steps.
BEGIN_PLUMED_FILE
# compute distance:
distance: DISTANCE ATOMS=2,5
# compute total energy (potential)
energy: ENERGY
# print distance on a file
PRINT ARG=distance
STRIDE=10
FILE=COLVAR
# print both variables on another file
PRINT ARG=distance,energy
STRIDE=1000 FILE=COLVAR_ALL
Notice that DISTANCE and ENERGY are computed respectively every 10 and 1000 steps, that is only when required.
6.15.1
FLUSH
This is part of the generic module
This command instructs plumed to flush all the open files with a user specified frequency. Notice that all files are
flushed anyway every 10000 steps.
This is useful for preventing data loss that would otherwise arise as a consequence of the code storing data for
printing in the buffers. Notice that wherever it is written in the plumed input file, it will flush all the open files.
Compulsory keywords
STRIDE
the frequency with which all the open files should be flushed
Examples
A command like this in the input will instruct plumed to flush all the output files every 100 steps
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=1,10
Generated by Doxygen
374
Analysis
PRINT ARG=d1 STRIDE=5 FILE=colvar1
FLUSH STRIDE=100
d2: DISTANCE ATOMS=2,11
# also this print is flushed every 100 steps:
PRINT ARG=d2 STRIDE=10 FILE=colvar2
(see also DISTANCE and PRINT).
6.16
UPDATE_IF
This is part of the generic module
Conditional update of other actions.
This action can be used to enable and disable the update step for the following actions depending on the value of
its arguments. This allows for example to extract snapshots with value of some CVs in a given range.
When called with MORE_THAN and/or LESS_THAN keywords, this action starts an if block. The block is executed
if all the arguments are less than all the respective values in the LESS_THAN keyword (if present) and all the
arguments are more than all the respective values in the MORE_THAN keyword (if present).
When called with the END flag, this action ends the corresponding IF block. Notice that in this case one should also
provide the ARG keyword. It is recommended to use the same ARG keyword that was used to begin the block, so
as to make the input more readable.
Of course, blocks can be nested at will.
There are many potential usages for this keyword. One might e.g. decide to analyze some variable only when
another variable is within a given range.
Warning
Notice that not all the possible usage make particular sense. For example, conditionally updating a METAD
keyword (that is: adding hills only if a variable is within a given range) can lead to unexpected results.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the quantities of interest should be output
Options
END
( default=off ) end
Generated by Doxygen
6.17 REWEIGHT_BIAS
375
ARG
the input for this action is the scalar output from one or more other actions. The particular
scalars that you will use are referenced using the label of the action. If the label appears on its
own then it is assumed that the Action calculates a single scalar value. The value of this scalar
is thus used as the input to this new action. If ∗ or ∗.∗ appears the scalars calculated by all the
proceeding actions in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE action labelled
dist may have three components x, y and z. To take just the x component you should use dist.x,
if you wish to take all three components then use dist.∗.More information on the referencing
of Actions can be found in the section of the manual on the PLUMED Getting Started. Scalar
values can also be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with the appropriate
flag. You can use multiple instances of this keyword i.e. ARG1, ARG2, ARG3...
LESS_THAN
upper bound
MORE_THAN
lower bound
Examples
The following input instructs plumed dump all the snapshots where an atom is in touch with the solute.
BEGIN_PLUMED_FILE
solute: GROUP ATOMS=1-124
coord: COORDINATION GROUPA=solute GROUPB=500 R_0=0.5
# A coordination number higher than 0.5 indicate that there is at least one
# atom of group ‘solute‘ at less than 5 A from atom number 500
UPDATE_IF ARG=coord MORE_THAN=0.5
DUMPATOMS ATOMS=solute,500 FILE=output.xyz
UPDATE_IF ARG=coord END
6.17
REWEIGHT_BIAS
This is part of the bias module
Calculate weights for ensemble averages that negate the effect the bias has on the region of phase space explored
If a static or pseudo-static bias V (x, t0 ) is acting on the system we can remove the bias and get the unbiased
probability distribution using:
Pt
hP (s0 , t)i =
t0
0
)
δ(s(x) − s0 ) exp + Vk(x,t
BT
P0t
V (x,t0 )
t exp + kB T
The weights calculated by this action are equal to exp +
V (x,t0 )
kB T
these weights can then be used in any action that
computes ensemble averages. For example this action can be used in tandem with HISTOGRAM or AVERAGE.
Compulsory keywords
Generated by Doxygen
376
Analysis
ARG
( default=∗.bias ) the biases that must be taken into account when reweighting
Options
TEMP
the system temperature. This is not required if your MD code passes this quantity to PLUMED
Examples
In the following example there is a fixed restraint on the distance between atoms 1 and 2. Clearly, this restraint will
have an effect on the region of phase space that will be sampled when an MD simulation is run using this variable.
Consequently, when the histogram as a function of the distance, x, is accumulated, we use reweighting into order
to discount the effect of the bias from our final histogram.
BEGIN_PLUMED_FILE
x: DISTANCE ATOMS=1,2
RESTRAINT ARG=x SLOPE=1.0 AT=0.0
bias: REWEIGHT_BIAS TEMP=300
HISTOGRAM ...
ARG=x
GRID_MIN=0.0
GRID_MAX=3.0
GRID_BIN=100
BANDWIDTH=0.1
LOGWEIGHTS=bias
LABEL=hB
... HISTOGRAM
DUMPGRID GRID=hB FILE=histoB STRIDE=1 FMT=%8.4f
6.18
REWEIGHT_METAD
This is part of the bias module
Calculate the weights configurations should contribute to the histogram in a simulation in which a metadynamics
bias acts upon the system.
This command allows you to use the reweighting algorithm discussed in [32] when constructing a histogram of the
configurations visited during a metadynamics simulation.
Compulsory keywords
ARG
( default=∗.rbias ) the biases that must be taken into account when reweighting
Generated by Doxygen
6.19 REWEIGHT_TEMP
377
Options
TEMP
the system temperature. This is not required if your MD code passes this quantity to PLUMED
Examples
In the following example there is a metadynamics bias acting on the distance between atoms 1 and 2. Clearly, this
bias will have an effect on the region of phase space that will be sampled when an MD simulation is run using this
variable. Consequently, when the histogram as a function of the angle, a, is accumulated, we use reweighting into
order to discount the effect of the bias from our final histogram. We do not use REWEIGHT_BIAS here, however, as
the bias changes with time. We thus use the reweighting algorithm for metadynamics instead. Notice also that we
have to specify how often we would like to calculate the c(t) reweighting factor and the grid over which we calculate
c(t) in the input to the METAD command.
BEGIN_PLUMED_FILE
a: ANGLE ATOMS=1,2,3
x: DISTANCE ATOMS=1,2
METAD ARG=x PACE=100 SIGMA=0.1 HEIGHT=1.5 BIASFACTOR=5 GRID_MIN=0 GRID_MAX=10 GRID_BIN=100 REWEIGHTING_NGRID=1
bias: REWEIGHT_METAD TEMP=300
HISTOGRAM ...
ARG=a
GRID_MIN=0.0
GRID_MAX=pi
GRID_BIN=100
BANDWIDTH=0.1
LOGWEIGHTS=bias
LABEL=hB
... HISTOGRAM
DUMPGRID GRID=hB FILE=histoB STRIDE=1 FMT=%8.4f
6.19
REWEIGHT_TEMP
This is part of the bias module
Calculate weights for ensemble averages allow for the computing of ensemble averages at temperatures
lower/higher than that used in your original simulation.
We can use our knowledge of the Boltzmann distribution in the canonical ensemble to reweight the data contained
in trajectories. Using this procedure we can take trajectory at temperature T1 and use it to extract probabilities at a
different temperature, T2 , using:
Pt
P (s0 , t) =
t0
h
i
0
)
δ(s(x) − s0 ) exp +( T11 − T12 U (x,t
kB
h
i
Pt
U (x,t0 )
1
1
t0 exp + T1 − T2
kB
h
The weights calculated by this action are equal to exp +(
1
T1
−
1
T2
i
U (x,t0 )
kB
and take the effect the bias has on
the system into account. These weights can be used in any action that computes ensemble averages. For example
this action can be used in tandem with HISTOGRAM or AVERAGE.
Generated by Doxygen
378
Analysis
Compulsory keywords
REWEIGHT_TEMP
reweight data from a trajectory at one temperature and output the probability distribution
at a second temperature. This is not possible during post processing.
Options
TEMP
the system temperature. This is not required if your MD code passes this quantity to PLUMED
Examples
The following input can be used to post process a molecular dynamics trajectory calculated at a temperature of 500
K. The HISTOGRAM as a function of the distance between atoms 1 and 2 that would have been obtained if the
simulation had been run at the lower temperature of 300 K is estimated using the data from the higher temperature
trajectory and output to a file.
BEGIN_PLUMED_FILE
x: DISTANCE ATOMS=1,2
aa: REWEIGHT_TEMP TEMP=500 REWEIGHT_TEMP=300
hB: HISTOGRAM ARG=x GRID_MIN=0.0 GRID_MAX=3.0 GRID_BIN=100 BANDWIDTH=0.1 LOGWEIGHTS=aa
DUMPGRID GRID=hB FILE=histoB
6.20
REWEIGHT_WHAM
This is part of the bias module
Compulsory keywords
ARG
( default=∗.bias ) the biases that must be taken into account when reweighting
MAXITER
( default=1000 ) maximum number of iterations for WHAM algorithm
WHAMTOL
( default=1e-10 ) threshold for convergence of WHAM algorithm
Options
TEMP
the system temperature. This is not required if your MD code passes this quantity to PLUMED
Examples
Generated by Doxygen
6.22 WHAM_WEIGHTS
6.21
379
WHAM_HISTOGRAM
This is part of the analysis module
This can be used to output the a histogram using the weighted histogram technique
Compulsory keywords
ARG
the arguments that you would like to make the histogram for
BIAS
( default=∗.bias ) the value of the biases to use when performing WHAM
TEMP
the temperature at which the simulation was run
STRIDE
( default=1 ) the frequency with which the data should be stored to perform WHAM
GRID_MIN
the minimum to use for the grid
GRID_MAX
the maximum to use for the grid
GRID_BIN
the number of bins to use for the grid
Options
BANDWIDTH
the bandwidth for kernel density estimation
Examples
6.22
WHAM_WEIGHTS
This is part of the analysis module
This can be used to output the data that has been stored in an Analysis object.
Compulsory keywords
BIAS
( default=∗.bias ) the value of the biases to use when performing WHAM
TEMP
the temperature at which the simulation was run
STRIDE
( default=1 ) the frequency with which the bias should be stored to perform WHAM
FILE
the file on which to output the WHAM weights
Options
Generated by Doxygen
380
Analysis
FMT
the format to use for the real numbers in the output file
Examples
6.23
AVERAGE
This is part of the analysis module
Calculate the ensemble average of a collective variable
The ensemble average for a non-periodic, collective variable, s is given by the following expression:
Pt
hsi =
0
t =0
P
t
w(t0 )s(t0 )
t0 =0
w(t0 )
Here the sum runs over a the trajectory and s(t0 ) is used to denote the value of the collective variable at time t0 .
The final quantity evaluated is a weighted average as the weights, w(t0 ), allow us to negate the effect any bias
might have on the region of phase space sampled by the system. This is discussed in the section of the manual on
Analysis.
When the variable is periodic (e.g. TORSION) and has a value, s, in a ≤ s ≤ b the ensemble average is evaluated
using:
w(t0 ) sin
2π[s(t0 )−a]
b−a
0
t =0 w(t ) cos
2π[s(t0 )−a]
b−a
Pt
hsi = a +
b−a
arctan P
t
2π
0
t0 =0
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the data should be collected and added to the
quantity being averaged
CLEAR
( default=0 ) the frequency with which to clear all the accumulated data. The default value
of 0 implies that all the data will be used and that the grid will never be cleared
NORMALIZATION
( default=true ) This controls how the data is normalized it can be set equal to true, false
or ndata. The differences between these options are explained in the manual page for
HISTOGRAM
Options
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
Generated by Doxygen
6.24 HISTOGRAM
381
LOGWEIGHTS
list of actions that calculates log weights that should be used to weight configurations when
calculating averages
ARG
the input for this action is the scalar output from one or more other actions. The particular
scalars that you will use are referenced using the label of the action. If the label appears on
its own then it is assumed that the Action calculates a single scalar value. The value of this
scalar is thus used as the input to this new action. If ∗ or ∗.∗ appears the scalars calculated
by all the proceeding actions in the input file are taken. Some actions have multi-component
outputs and each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x component you
should use dist.x, if you wish to take all three components then use dist.∗.More information
on the referencing of Actions can be found in the section of the manual on the PLUMED
Getting Started. Scalar values can also be referenced using POSIX regular expressions as
detailed in the section on Regular Expressions. To use this feature you you must compile
PLUMED with the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
The following example calculates the ensemble average for the distance between atoms 1 and 2 and output this to
a file called COLVAR. In this example it is assumed that no bias is acting on the system and that the weights, w(t0 )
in the formulae above can thus all be set equal to one.
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=1,2
d1a: AVERAGE ARG=d1
PRINT ARG=d1a FILE=colvar STRIDE=100
The following example calculates the ensemble average for the torsional angle involving atoms 1, 2, 3 and 4. At
variance with the previous example this quantity is periodic so the second formula in the above introduction is used
to calculate the average. Furthermore, by using the CLEAR keyword we have specified that block averages are to
be calculated. Consequently, after 100 steps all the information acquired thus far in the simulation is forgotten and
the process of averaging is begun again. The quantities output in the colvar file are thus the block averages taken
over the first 100 frames of the trajectory, the block average over the second 100 frames of trajectory and so on.
BEGIN_PLUMED_FILE
t1: TORSION ATOMS=1,2,3,4
t1a: AVERAGE ARG=t1 CLEAR=100
PRINT ARG=t1a FILE=colvar STRIDE=100
This third example incorporates a bias. Notice that the effect the bias has on the ensemble average is removed by
taking advantage of the REWEIGHT_BIAS method. The final ensemble averages output to the file are thus block
ensemble averages for the unbiased canonical ensemble at a temperature of 300 K.
BEGIN_PLUMED_FILE
t1: TORSION ATOMS=1,2,3,4
RESTRAINT ARG=t1 AT=pi KAPPA=100.
ww: REWEIGHT_BIAS TEMP=300
t1a: AVERAGE ARG=t1 LOGWEIGHTS=ww CLEAR=100
PRINT ARG=t1a FILE=colvar STRIDE=100
6.24
HISTOGRAM
Generated by Doxygen
382
Analysis
This is part of the analysis module
Accumulate the average probability density along a few CVs from a trajectory.
When using this method it is supposed that you have some collective variable ζ that gives a reasonable description
of some physical or chemical phenomenon. As an example of what we mean by this suppose you wish to examine
the following SN2 reaction:
OH− + CH3 Cl → CH3 OH + Cl−
The distance between the chlorine atom and the carbon is an excellent collective variable, ζ , in this case because
this distance is short for the reactant,
3 Cl, because the carbon and chlorine are chemically bonded, and because
it is long for the product state when these two atoms are not chemically bonded. We thus might want to accumulate
the probability density, P (ζ), as a function of this distance as this will provide us with information about the overall
likelihood of the reaction. Furthermore, the free energy, F (ζ), is related to this probability density via:
CH
F (ζ) = −kB T ln P (ζ)
Accumulating these probability densities is precisely what this Action can be used to do. Furthermore, the conversion of the histogram to the free energy can be achieved by using the method CONVERT_TO_FES.
We calculate histograms within PLUMED using a method known as kernel density estimation, which you can read
more about here:
https://en.wikipedia.org/wiki/Kernel_density_estimation
In PLUMED the value of ζ at each discrete instant in time in the trajectory is accumulated. A kernel, K(ζ −ζ(t0 ), σ),
centered at the current value, ζ(t), of this quantity is generated with a bandwidth σ , which is set by the user. These
kernels are then used to accumulate the ensemble average for the probability density:
Pt
hP (ζ)i =
t0 =0
w(t0 )K(ζ − ζ(t0 ), σ)
Pt
0
t0 =0 w(t )
Here the sums run over a portion of the trajectory specified by the user. The final quantity evaluated is a weighted
average as the weights, w(t0 ), allow us to negate the effect any bias might have on the region of phase space
sampled by the system. This is discussed in the section of the manual on Analysis.
A discrete analogue of kernel density estimation can also be used. In this analogue the kernels in the above
formula are replaced by Dirac delta functions. When this method is used the final function calculated is no longer a
probability density - it is instead a probability mass function as each element of the function tells you the value of an
integral between two points on your grid rather than the value of a (continuous) function on a grid.
Additional material and examples can be also found in the tutorials Belfast tutorial: Analyzing CVs and
Lugano tutorial: Analyzing CVs.
A note on block averaging and errors
Generated by Doxygen
6.24 HISTOGRAM
383
Some particularly important issues related to the convergence of histograms and the estimation of error bars around
the ensemble averages you calculate are covered in Trieste tutorial: Averaging, histograms and block analysis. The
technique for estimating error bars that is known as block averaging is introduced in this tutorial. The essence of
this technique is that the trajectory is split into a set of blocks and separate ensemble averages are calculated from
each separate block of data. If {Ai } is the set of N block averages that are obtained from this technique then the
final error bar is calculated as:
v
u
N
u
X
error = t N1 N 1− 1 (A2i − hAi)2
i=1
where
hAi =
N
1 X
Ai
N i=1
If the simulation is biased and reweighting is performed then life is a little more complex as each of the block
averages should be calculated as a weighted average. Furthermore, the weights should be taken into account
when the final ensemble and error bars are calculated. As such the error should be:
v
u
PN
N
u1
X
i=1 Wi
t
Wi (A2i − hAi)2
error = N PN
P
PN
N
2/
W
W
W
−
i
i
i
i=1
i=1
i=1
i=1
where Wi is the sum of all the weights for the ith block of data.
If we wish to calculate a normalized histogram we must calculate ensemble averages from our biased simulation
using:
PM
t=1
hH(x)i =
wt K(x − xt , σ)
PM
t=1 wt
where the sums runs over the trajectory, wt is the weight of the tth trajectory frame, xt is the value of the CV for the
tth trajectory frame and K is a kernel function centered on xt with bandwidth σ . The quantity that is evaluated is
the value of the normalized histogram at point x. The following ensemble average will be calculated if you use the
NORMALIZATION=true option in HISTOGRAM. If the ensemble average is calculated in this way we must calculate
the associated error bars from our block averages using the second of the expressions above.
A number of works have shown that when biased simulations are performed it is often better to calculate an estimate
of the histogram that is not normalized using:
hH(x)i =
M
1 X
wt K(x − xt , σ)
M t=1
instead of the expression above. As such this is what is done by default in HISTOGRAM or if the NORMALIZAT←ION=ndata option is used. When the histogram is calculated in this second way the first of the two formula above
can be used when calculating error bars from block averages.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the data should be collected and added to the
quantity being averaged
CLEAR
( default=0 ) the frequency with which to clear all the accumulated data. The default value
of 0 implies that all the data will be used and that the grid will never be cleared
BANDWIDTH
the bandwidths for kernel density estimation
KERNEL
( default=gaussian ) the kernel function you are using. More details on the kernels available in plumed plumed can be found in kernelfunctions.
NORMALIZATION
( default=ndata ) This controls how the data is normalized it can be set equal to true, false
or ndata. See above for an explanation
Generated by Doxygen
GRID_MIN
the lower bounds for the grid
GRID_MAX
the upper bounds for the grid
384
Analysis
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
LOGWEIGHTS
list of actions that calculates log weights that should be used to weight configurations
when calculating averages
CONCENTRATION
the concentration parameter for Von Mises-Fisher distributions
ARG
the input for this action is the scalar output from one or more other actions. The particular
scalars that you will use are referenced using the label of the action. If the label appears
on its own then it is assumed that the Action calculates a single scalar value. The value
of this scalar is thus used as the input to this new action. If ∗ or ∗.∗ appears the scalars
calculated by all the proceeding actions in the input file are taken. Some actions have
multi-component outputs and each component of the output has a specific label. For
example a DISTANCE action labelled dist may have three components x, y and z. To
take just the x component you should use dist.x, if you wish to take all three components
then use dist.∗.More information on the referencing of Actions can be found in the section
of the manual on the PLUMED Getting Started. Scalar values can also be referenced
using POSIX regular expressions as detailed in the section on Regular Expressions. To
use this feature you you must compile PLUMED with the appropriate flag. You can use
multiple instances of this keyword i.e. ARG1, ARG2, ARG3...
DATA
input data from action with vessel and compute histogram
VECTORS
input three dimensional vectors for computing histogram
GRID_BIN
the number of bins for the grid
GRID_SPACING
the approximate grid spacing (to be used as an alternative or together with GRID_BIN)
UPDATE_FROM
Only update this action from this time
UPDATE_UNTIL
Only update this action until this time
Examples
The following input monitors two torsional angles during a simulation and outputs a continuous histogram as a
function of them at the end of the simulation.
BEGIN_PLUMED_FILE
TORSION ATOMS=1,2,3,4 LABEL=r1
TORSION ATOMS=2,3,4,5 LABEL=r2
HISTOGRAM ...
ARG=r1,r2
GRID_MIN=-3.14,-3.14
GRID_MAX=3.14,3.14
GRID_BIN=200,200
BANDWIDTH=0.05,0.05
LABEL=hh
... HISTOGRAM
DUMPGRID GRID=hh FILE=histo
The following input monitors two torsional angles during a simulation and outputs a discrete histogram as a function
of them at the end of the simulation.
BEGIN_PLUMED_FILE
TORSION ATOMS=1,2,3,4 LABEL=r1
TORSION ATOMS=2,3,4,5 LABEL=r2
Generated by Doxygen
6.25 MULTICOLVARDENS
385
HISTOGRAM ...
ARG=r1,r2
KERNEL=DISCRETE
GRID_MIN=-3.14,-3.14
GRID_MAX=3.14,3.14
GRID_BIN=200,200
LABEL=hh
... HISTOGRAM
DUMPGRID GRID=hh FILE=histo
The following input monitors two torsional angles during a simulation and outputs the histogram accumulated thus
far every 100000 steps.
BEGIN_PLUMED_FILE
TORSION ATOMS=1,2,3,4 LABEL=r1
TORSION ATOMS=2,3,4,5 LABEL=r2
HISTOGRAM ...
ARG=r1,r2
GRID_MIN=-3.14,-3.14
GRID_MAX=3.14,3.14
GRID_BIN=200,200
BANDWIDTH=0.05,0.05
LABEL=hh
... HISTOGRAM
DUMPGRID GRID=hh FILE=histo STRIDE=100000
The following input monitors two torsional angles during a simulation and outputs a separate histogram for each
100000 steps worth of trajectory. Notice how the CLEAR keyword is used here and how it is not used in the
previous example.
BEGIN_PLUMED_FILE
TORSION ATOMS=1,2,3,4 LABEL=r1
TORSION ATOMS=2,3,4,5 LABEL=r2
HISTOGRAM ...
ARG=r1,r2 CLEAR=100000
GRID_MIN=-3.14,-3.14
GRID_MAX=3.14,3.14
GRID_BIN=200,200
BANDWIDTH=0.05,0.05
GRID_WFILE=histo
LABEL=hh
... HISTOGRAM
DUMPGRID GRID=hh FILE=histo STRIDE=100000
6.25
MULTICOLVARDENS
This is part of the multicolvar module
Evaluate the average value of a multicolvar on a grid.
This keyword allows one to construct a phase field representation for a symmetry function from an atomistic description. If each atom has an associated order parameter, φi then a smooth phase field function φ(r) can be computed
using:
P
K(r − ri )φi
φ(r) = Pi
i K(r − ri )
Generated by Doxygen
386
Analysis
where ri is the position of atom i, the sums run over all the atoms input and K(r − ri ) is one of the kernelfunctions
implemented in plumed. This action calculates the above function on a grid, which can then be used in the input to
further actions.
The atoms involved can be specified using
ORIGIN
we will use the position of this atom as the origin. For more information on how to specify lists of
atoms see Groups and Virtual Atoms
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the data should be collected and added to the
quantity being averaged
CLEAR
( default=0 ) the frequency with which to clear all the accumulated data. The default value
of 0 implies that all the data will be used and that the grid will never be cleared
NORMALIZATION
( default=true ) This controls how the data is normalized it can be set equal to true, false
or ndata. The differences between these options are explained in the manual page for
HISTOGRAM
the bandwidths for kernel density estimation
BANDWIDTH
KERNEL
( default=gaussian ) the kernel function you are using. More details on the kernels available in plumed plumed can be found in kernelfunctions.
DATA
the multicolvar which you would like to calculate the density profile for
DIR
the direction in which to calculate the density profile
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
FRACTIONAL
( default=off ) use fractional coordinates for the various axes
XREDUCED
( default=off ) limit the calculation of the density/average to a portion of the z-axis only
YREDUCED
( default=off ) limit the calculation of the density/average to a portion of the y-axis only
ZREDUCED
( default=off ) limit the calculation of the density/average to a portion of the z-axis only
LOGWEIGHTS
list of actions that calculates log weights that should be used to weight configurations
when calculating averages
CONCENTRATION
the concentration parameter for Von Mises-Fisher distributions
NBINS
the number of bins to use to represent the density profile
SPACING
the approximate grid spacing (to be used as an alternative or together with NBINS)
XLOWER
this is required if you are using XREDUCED. It specifies the lower bound for the region of
the x-axis that for which you are calculating the density/average
XUPPER
this is required if you are using XREDUCED. It specifies the upper bound for the region
of the x-axis that for which you are calculating the density/average
YLOWER
this is required if you are using YREDUCED. It specifies the lower bound for the region of
the y-axis that for which you are calculating the density/average
YUPPER
this is required if you are using YREDUCED. It specifies the upper bound for the region
of the y-axis that for which you are calculating the density/average
Generated by Doxygen
6.26 CONVERT_TO_FES
387
ZLOWER
this is required if you are using ZREDUCED. It specifies the lower bound for the region of
the z-axis that for which you are calculating the density/average
ZUPPER
this is required if you are using ZREDUCED. It specifies the upper bound for the region
of the z-axis that for which you are calculating the density/average
Examples
The following example shows perhaps the simplest way in which this action can be used. The following input
computes the density of atoms at each
Ppoint on the grid and outputs this quantity to a file. In other words this input
instructs plumed to calculate ρ(r) = i K(r − ri )
BEGIN_PLUMED_FILE
dens: DENSITY SPECIES=1-100
grid: MULTICOLVARDENS DATA=dens ORIGIN=1 DIR=xyz NBINS=100,100,100 BANDWIDTH=0.05,0.05,0.05 STRIDE=1
DUMPGRID GRID=grid STRIDE=500 FILE=density
In the above example density is added to the grid on every step. The PRINT_GRID instruction thus tells PLUMED
to output the average density at each point on the grid every 500 steps of simulation. Notice that the that grid output
on step 1000 is an average over all 1000 frames of the trajectory. If you would like to analyze these two blocks of
data separately you must use the CLEAR flag.
This second example computes an order parameter (in this case FCCUBIC) and constructs a phase field model for
this order parameter using the equation above.
BEGIN_PLUMED_FILE
fcc: FCCUBIC SPECIES=1-5184 SWITCH={CUBIC D_0=1.2 D_MAX=1.5} ALPHA=27
dens: MULTICOLVARDENS DATA=fcc ORIGIN=1 DIR=xyz NBINS=14,14,28 BANDWIDTH=1.0,1.0,1.0 STRIDE=1 CLEAR=1
DUMPCUBE GRID=dens STRIDE=1 FILE=dens.cube
In this example the phase field model is computed and output to a file on every step of the simulation. Furthermore,
because the CLEAR=1 keyword is set on the MULTICOLVARDENS line each Gaussian cube file output is a phase
field model for a particular trajectory frame. The average value accumulated thus far is cleared at the start of every
single timestep and there is no averaging over trajectory frames in this case.
6.26
CONVERT_TO_FES
Convert a histogram, H(x), to a free energy surface using F (x) = −kB T ln H(x).
This action allows you to take a free energy surface that was calculated using the HISTOGRAM action and to
convert it to a free energy surface. This transformation performed by doing:
F (x) = −kB T ln H(x)
The free energy calculated on a grid is output by this action and can be printed using DUMPGRID
Compulsory keywords
Generated by Doxygen
388
Analysis
GRID
the action that creates the input grid you would like to use
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
CONCENTRATION
the concentration parameter for Von Mises-Fisher distributions
COMPONENT
if your input is a vector field use this to specify the component of the input vector field for
which you wish to use
TEMP
the temperature at which you are operating
Examples
This is a typical example showing how CONVERT_TO_FES might be used when post processing a trajectory. The
input below calculates the free energy as a function of the distance between atom 1 and atom 2. This is done
by accumulating a histogram as a function of this distance using kernel density estimation and the HISTOGRAM
action. All the data within this trajectory is used in the construction of this HISTOGRAM. Finally, once all the data
has been read in, the histogram is converted to a free energy using the formula above and the free energy is output
to a file called fes.dat
BEGIN_PLUMED_FILE
x: DISTANCE ATOMS=1,2
hA1: HISTOGRAM ARG=x GRID_MIN=0.0 GRID_MAX=3.0 GRID_BIN=100 BANDWIDTH=0.1
ff: CONVERT_TO_FES GRID=hA1 TEMP=300
DUMPGRID GRID=ff FILE=fes.dat
6.27
DUMPCUBE
Output a three dimensional grid using the Gaussian cube file format.
Suppose you have calculated the value of a function on a three dimensional grid. This function might be
a HISTOGRAM or it might be a free energy energy surface that was calculated from this histogram by
using CONVERT_TO_FES. Alternatively, your function might be a phase-field that was calculated using
MULTICOLVARDENS. Whatever the function is, however, you obviously cannot show it using a typical contour plotting program such as gnuplot as you have three input variables.
Tools like VMD have nice features for plotting these types of three dimensional functions but typically you are
required to use a Gaussian cube file format to input the data. This action thus allows you to output a function
evaluated on a grid to a Gaussian cube file format.
Compulsory keywords
GRID
the action that creates the grid you would like to output
STRIDE
( default=0 ) the frequency with which the grid should be output to the file. The default value of 0
Generated by Doxygen
ensures that the grid is only output at the end of the trajectory
FILE
( default=density ) the file on which to write the grid.
REPLICA
( default=0 ) the replicas for which you would like to output this information
6.28 DUMPGRID
389
Options
FMT
the format that should be used to output real numbers
COMPONENT
if your input is a vector field use this to specify the component of the input vector field for which
you wish to output
Examples
The input below can be used to post process a trajectory. A histogram as a function of the distance between atoms
1 and 2, the distance between atom 1 and 3 and the angle between the vector connecting atoms 1 and 2 and 1
and 3 is computed using kernel density estimation. Once all the data contained in the trajectory has been read in
and all the kernels have been added the resulting histogram is output to a file called histoA1.cube. This file has the
Gaussian cube file format. The histogram can thus be visualized using tools such as VMD.
BEGIN_PLUMED_FILE
x1: DISTANCE ATOMS=1,2
x2: DISTANCE ATOMS=1,3
x3: ANGLE ATOMS=1,2,3
hA1: HISTOGRAM ARG=x1,x2,x3 GRID_MIN=0.0,0.0,0.0 GRID_MAX=3.0,3.0,3.0 GRID_BIN=10,10,10 BANDWIDTH=1.0,1.0,1.0
DUMPCUBE GRID=hA1 FILE=histoA1.cube
6.28
DUMPGRID
Output the function on the grid to a file with the PLUMED grid format.
PLUMED provides a number of actions that calculate the values of functions on grids. For instance, whenever
you calculate a free energy as a function of a collective variable using HISTOGRAM and CONVERT_TO_FES you
will generally want to output the value of the free energy at a number of points on a discrete grid that covers the
CV space uniformly. Alternatively you may want to calculate what value some symmetry function takes at different
points inside your simulation cell using MULTICOLVARDENS.
This action allows you to output these functions calculated on a grid using a format that can be read in using gnuplot
and other such plotting programs. The file output using this action will have a header that contains some essential
information about the function plotted and that looks something like this:
#!
#!
#!
#!
#!
#!
#!
#!
#!
#!
FIELDS x y hA1 dhA1_x dhA1_x
SET normalisation
2.0000
SET min_x 0.0
SET max_x 3.0
SET nbins_x 100
SET periodic_x false
SET min_y 0.0
SET max_y 3.0
SET nbins_y 100
SET periodic_y false
The header shown here tells us that we have grid showing the values that a function with two arguments x and
y takes at various points in our cell. The lines beneath the first line then tell us a little bit about these two input
arguments.
The remaining lines of the file give us information on the positions of our grid points and the value the function and
its partial derivatives with respect to x and y. If the header is as above a list of values of the function that have x=0
and 100 values of y between 0.0 and 3.0 will be provided. This block of data will be followed with a blank line. There
will then be a second block of values which will all have been evaluated the same value of x and all possible values
for y. This block is then followed by a blank line again and this pattern continues until all points of the grid have been
covered.
Generated by Doxygen
390
Analysis
Compulsory keywords
GRID
the action that creates the grid you would like to output
STRIDE
( default=0 ) the frequency with which the grid should be output to the file. The default value of 0
ensures that the grid is only output at the end of the trajectory
FILE
( default=density ) the file on which to write the grid.
REPLICA
( default=0 ) the replicas for which you would like to output this information
Options
FMT
the format that should be used to output real numbers
Examples
The following input monitors two torsional angles during a simulation and outputs a continuous histogram as a
function of them at the end of the simulation.
BEGIN_PLUMED_FILE
TORSION ATOMS=1,2,3,4 LABEL=r1
TORSION ATOMS=2,3,4,5 LABEL=r2
HISTOGRAM ...
ARG=r1,r2
GRID_MIN=-3.14,-3.14
GRID_MAX=3.14,3.14
GRID_BIN=200,200
BANDWIDTH=0.05,0.05
LABEL=hh
... HISTOGRAM
DUMPGRID GRID=hh FILE=histo
The following input monitors two torsional angles during a simulation and outputs a discrete histogram as a function
of them at the end of the simulation.
BEGIN_PLUMED_FILE
TORSION ATOMS=1,2,3,4 LABEL=r1
TORSION ATOMS=2,3,4,5 LABEL=r2
HISTOGRAM ...
ARG=r1,r2
KERNEL=DISCRETE
GRID_MIN=-3.14,-3.14
GRID_MAX=3.14,3.14
GRID_BIN=200,200
LABEL=hh
... HISTOGRAM
DUMPGRID GRID=hh FILE=histo
The following input monitors two torsional angles during a simulation and outputs the histogram accumulated thus
far every 100000 steps.
Generated by Doxygen
6.29 FIND_CONTOUR_SURFACE
391
BEGIN_PLUMED_FILE
TORSION ATOMS=1,2,3,4 LABEL=r1
TORSION ATOMS=2,3,4,5 LABEL=r2
HISTOGRAM ...
ARG=r1,r2
GRID_MIN=-3.14,-3.14
GRID_MAX=3.14,3.14
GRID_BIN=200,200
BANDWIDTH=0.05,0.05
LABEL=hh
... HISTOGRAM
DUMPGRID GRID=hh FILE=histo STRIDE=100000
The following input monitors two torsional angles during a simulation and outputs a separate histogram for each
100000 steps worth of trajectory. Notice how the CLEAR keyword is used here and how it is not used in the
previous example.
BEGIN_PLUMED_FILE
TORSION ATOMS=1,2,3,4 LABEL=r1
TORSION ATOMS=2,3,4,5 LABEL=r2
HISTOGRAM ...
ARG=r1,r2 CLEAR=100000
GRID_MIN=-3.14,-3.14
GRID_MAX=3.14,3.14
GRID_BIN=200,200
BANDWIDTH=0.05,0.05
GRID_WFILE=histo
LABEL=hh
... HISTOGRAM
DUMPGRID GRID=hh FILE=histo STRIDE=100000
6.29
FIND_CONTOUR_SURFACE
Find an isocontour by searching along either the x, y or z direction.
As discussed in the part of the manual on Analysis PLUMED contains a number of tools that allow you to calculate
a function on a grid. The function on this grid might be a HISTOGRAM as a function of a few collective variables or
it might be a phase field that has been calculated using MULTICOLVARDENS. If this function has one or two input
arguments it is relatively straightforward to plot the function. If by contrast the data has a three dimensions it can be
difficult to visualize.
This action provides one tool for visualizing these functions. It can be used to search for a set of points on a contour
where the function takes a particular value. In other words, for the function f (x, y, z) this action would find a set of
points {xc , yc , zc } that have:
f (xc , yc , zc ) − c = 0
where c is some constant value that is specified by the user. The points on this contour are find by searching along
lines that run parallel to the x, y or z axis of the simulation cell. The result is, therefore, a two dimensional function
evaluated on a grid that gives us the height of the interface as a function of two coordinates.
It is important to note that this action can only be used to detect contours in three dimensional functions. In addition,
this action will fail to find the full set of contour points if the contour does not have the same topology as an infinite
plane. If you are uncertain that the isocontours in your function have the appropriate topology you should use
FIND_CONTOUR in place of FIND_CONTOUR_SURFACE.
Compulsory keywords
Generated by Doxygen
392
Analysis
STRIDE
( default=1 ) the frequency with which the data should be collected and added to the
quantity being averaged
CLEAR
( default=0 ) the frequency with which to clear all the accumulated data. The default value
of 0 implies that all the data will be used and that the grid will never be cleared
NORMALIZATION
GRID
( default=true ) This controls how the data is normalized it can be set equal to true, false
or ndata. The differences between these options are explained in the manual page for
HISTOGRAM
the action that creates the input grid you would like to use
CONTOUR
the value we would like to draw the contour at in the space
SEARCHDIR
In which directions do you wish to search for the contour.
BUFFER
( default=0 ) number of buffer grid points around location where grid was found on last
step. If this is zero the full grid is calculated on each step
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
LOGWEIGHTS
list of actions that calculates log weights that should be used to weight configurations
when calculating averages
CONCENTRATION
the concentration parameter for Von Mises-Fisher distributions
COMPONENT
if your input is a vector field use this to specify the component of the input vector field for
which you wish to use
Examples
The input shown below was used to analyze the results from a simulation of an interface between solid and molten
Lennard Jones. The interface between the solid and the liquid was set up in the plane perpendicular to the z
direction of the simulation cell. The input below calculates something akin to a Willard-Chandler dividing surface
[33] between the solid phase and the liquid phase. There are two of these interfaces within the simulation box
because of the periodic boundary conditions but we were able to determine that one of these two surfaces lies in
a particular part of the simulation box. The input below detects the height profile of one of these two interfaces. It
does so by computing a phase field average of the FCCUBIC symmetry function using the MULTICOLVARDENS
action. Notice that we use the fact that we know roughly where the interface is when specifying how this phase field
is to be calculated and specify the region over the z -axis in which we are going to search for the phase field in the
line defining the MULTICOLVARDENS. Once we have calculated the phase field we search for contour points on
the lines that run parallel to the z -direction of the cell box using the FIND_CONTOUR_SURFACE command. The
final result is a 14 × 14 grid of values for the height of the interface as a function of the (x, y) position. This grid is
then output to a file called contour2.dat.
Notice that the commands below calculate the instantaneous position of the surface separating the solid and liquid
and that as such the accumulated average is cleared on every step.
BEGIN_PLUMED_FILE
UNITS NATURAL
FCCUBIC ...
SPECIES=1-96000 SWITCH={CUBIC D_0=1.2 D_MAX=1.5}
ALPHA=27 PHI=0.0 THETA=-1.5708 PSI=-2.35619 LABEL=fcc
... FCCUBIC
dens2: MULTICOLVARDENS DATA=fcc ORIGIN=1 DIR=xyz NBINS=14,14,50 ZREDUCED ZLOWER=6.0 ZUPPER=11.0 BANDWIDTH=1.0,
ss2: FIND_CONTOUR_SURFACE GRID=dens2 CONTOUR=0.42 SEARCHDIR=z STRIDE=1 CLEAR=1
DUMPGRID GRID=ss2 FILE=contour2.dat FMT=%8.4f STRIDE=1
Generated by Doxygen
6.30 FIND_CONTOUR
6.30
393
FIND_CONTOUR
Find an isocontour in a smooth function.
As discussed in the part of the manual on Analysis PLUMED contains a number of tools that allow you to calculate
a function on a grid. The function on this grid might be a HISTOGRAM as a function of a few collective variables or
it might be a phase field that has been calculated using MULTICOLVARDENS. If this function has one or two input
arguments it is relatively straightforward to plot the function. If by contrast the data has a three or more dimensions
it can be difficult to visualize.
This action provides one tool for visualizing these functions. It can be used to search for a set of points on a contour
where the function takes a particular values. In other words, for the function f (x, y) this action would find a set of
points {xc , yc } that have:
f (xc , yc ) − c = 0
where c is some constant value that is specified by the user. The points on this contour are detected using a variant
on the marching squares or marching cubes algorithm, which you can find information on here:
https://en.wikipedia.org/wiki/Marching_squares https://en.wikipedia.org/wiki/←Marching_cubes
As such, and unlike FIND_CONTOUR_SURFACE or FIND_SPHERICAL_CONTOUR, the function input to this
action can have any dimension. Furthermore, the topology of the contour will be determined by the algorithm and
does not need to be specified by the user.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the data should be collected and added to the
quantity being averaged
CLEAR
( default=0 ) the frequency with which to clear all the accumulated data. The default value
of 0 implies that all the data will be used and that the grid will never be cleared
NORMALIZATION
GRID
( default=true ) This controls how the data is normalized it can be set equal to true, false
or ndata. The differences between these options are explained in the manual page for
HISTOGRAM
the action that creates the input grid you would like to use
CONTOUR
the value we would like to draw the contour at in the space
BUFFER
( default=0 ) number of buffer grid points around location where grid was found on last
step. If this is zero the full grid is calculated on each step
FILE
file on which to output coordinates
UNITS
( default=PLUMED ) the units in which to print out the coordinates. PLUMED means
internal PLUMED units
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
Generated by Doxygen
394
Analysis
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
LOGWEIGHTS
list of actions that calculates log weights that should be used to weight configurations
when calculating averages
CONCENTRATION
the concentration parameter for Von Mises-Fisher distributions
COMPONENT
if your input is a vector field use this to specify the component of the input vector field for
which you wish to use
PRECISION
The number of digits in trajectory file
Examples
The input below allows you to calculate something akin to a Willard-Chandler dividing surface [33]. The simulation
cell in this case contains a solid phase and a liquid phase. The Willard-Chandler surface is the surface that separates
the parts of the box containing the solid from the parts containing the liquid. To compute the position of this surface
the FCCUBIC symmetry function is calculated for each of the atoms in the system from on the geometry of the
atoms in the first coordination sphere of each of the atoms. These quantities are then transformed using a switching
function. This procedure generates a single number for each atom in the system and this quantity has a value of
one for atoms that are in parts of the box that resemble the solid structure and zero for atoms that are in parts of the
box that resemble the liquid. The position of a virtual atom is then computed using CENTER_OF_MULTICOLVAR
and a phase field model is constructed using MULTICOLVARDENS. These procedure ensures that we have a
continuous function that gives a measure of the average degree of solidness at each point in the simulation cell.
The Willard-Chandler dividing surface is calculated by finding a a set of points at which the value of this phase field
is equal to 0.5. This set of points is output to file called mycontour.dat. A new contour is found on every single step
for each frame that is read in.
BEGIN_PLUMED_FILE
UNITS NATURAL
FCCUBIC ...
SPECIES=1-96000 SWITCH={CUBIC D_0=1.2 D_MAX=1.5}
ALPHA=27 PHI=0.0 THETA=-1.5708 PSI=-2.35619 LABEL=fcc
... FCCUBIC
tfcc: MTRANSFORM_MORE DATA=fcc SWITCH={SMAP R_0=0.5 A=8 B=8}
center: CENTER_OF_MULTICOLVAR DATA=tfcc
MULTICOLVARDENS ...
DATA=tfcc ORIGIN=center DIR=xyz LABEL=dens
NBINS=80,80,80 BANDWIDTH=1.0,1.0,1.0 STRIDE=25
LABEL=dens STRIDE=1 CLEAR=1
... MULTICOLVARDENS
FIND_CONTOUR GRID=dens CONTOUR=0.5 FILE=mycontour.dat
6.31
FIND_SPHERICAL_CONTOUR
Find an isocontour in a three dimensional grid by searching over a Fibonacci sphere.
As discussed in the part of the manual on Analysis PLUMED contains a number of tools that allow you to calculate
a function on a grid. The function on this grid might be a HISTOGRAM as a function of a few collective variables or
it might be a phase field that has been calculated using MULTICOLVARDENS. If this function has one or two input
arguments it is relatively straightforward to plot the function. If by contrast the data has a three dimensions it can be
difficult to visualize.
This action provides one tool for visualizing these functions. It can be used to search for a set of points on a contour
where the function takes a particular value. In other words, for the function f (x, y, z) this action would find a set of
points {xc , yc , zc } that have:
Generated by Doxygen
6.31 FIND_SPHERICAL_CONTOUR
395
f (xc , yc , zc ) − c = 0
where c is some constant value that is specified by the user. The points on this contour are find by searching along
a set of equally spaced radii of a sphere that centered at on particular, user-specified atom or virtual atom. To
ensure that these search radii are equally spaced on the surface of the sphere the search directions are generated
by using a Fibonacci spiral projected on a sphere. In other words, the search directions are given by:
ri =
√
2i
1p
1 − y 2 sin(φ)
1 − y cos(φ) − 1 +
n
n
2
where y is the quantity second component of the vector defined above, n is the number of directions to look in and
φ is
φ = (i + R, n)π(3 −
√
5)
where R is a random variable between 0 and n − 1 that is generated during the read in of the input file and that is
fixed during the whole calculation.
It is important to note that this action can only be used to detect contours in three dimensional functions. In addition,
this action will fail to find the full set of contour points if the contour does not have the same topology as a sphere. If
you are uncertain that the isocontours in your function have a spherical topology you should use FIND_CONTOUR
in place of FIND_SPHERICAL_CONTOUR.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the data should be collected and added to the
quantity being averaged
CLEAR
( default=0 ) the frequency with which to clear all the accumulated data. The default value
of 0 implies that all the data will be used and that the grid will never be cleared
NORMALIZATION
GRID
( default=true ) This controls how the data is normalized it can be set equal to true, false
or ndata. The differences between these options are explained in the manual page for
HISTOGRAM
the action that creates the input grid you would like to use
CONTOUR
the value we would like to draw the contour at in the space
NPOINTS
the number of points for which we are looking for the contour
INNER_RADIUS
OUTER_RADIUS
NBINS
the minimum radius on which to look for the contour
the outer radius on which to look for the contour
( default=1 ) the number of discrete sections in which to divide the distance between the
inner and outer radius when searching for a contour
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
Generated by Doxygen
396
Analysis
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
LOGWEIGHTS
list of actions that calculates log weights that should be used to weight configurations
when calculating averages
CONCENTRATION
the concentration parameter for Von Mises-Fisher distributions
COMPONENT
if your input is a vector field use this to specify the component of the input vector field for
which you wish to use
Examples
The following input demonstrates how this action can be used. The input here is used to study the shape of a
droplet that has been formed during the condensation of Lennard Jones from the vapor. The input below achieves
this by calculating the coordination numbers of all the atoms within the gas. Obviously, those atoms within the
droplet will have a large value for the coordination number while the isolated atoms in the gas will have a low value.
As such we can detect the sizes of the droplets by constructing a CONTACT_MATRIX whose ij element tells us
whether atom i and atom j have coordination number that is greater that two. The atoms within the various droplets
within the system can then be found by performing a DFSCLUSTERING on this matrix to detect the connected
components. We can take the largest of these connected components and find the center of the droplet by exploiting
the functionality within CENTER_OF_MULTICOLVAR. We can then construct a phase field based on the positions
of the atoms in the largest cluster and the values of the coordination numbers of these atoms. The final line in the
input then finds the a set of points on the dividing surface that separates the droplet from the surrounding gas. The
value of the phase field on this isocontour is equal to 0.75.
BEGIN_PLUMED_FILE
# Calculate coordination numbers
c1: COORDINATIONNUMBER SPECIES=1-512 SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0}
# Select coordination numbers that are more than 2.0
cf: MFILTER_MORE DATA=c1 SWITCH={RATIONAL D_0=2.0 R_0=0.1} LOWMEM
# Build a contact matrix
mat: CONTACT_MATRIX ATOMS=cf SWITCH={EXP D_0=4.0 R_0=0.5 D_MAX=6.0}
# Find largest cluster
dfs: DFSCLUSTERING MATRIX=mat
clust1: CLUSTER_PROPERTIES CLUSTERS=dfs CLUSTER=1
# Find center of largest cluster
trans1: MTRANSFORM_MORE DATA=clust1 SWITCH={RATIONAL D_0=2.0 R_0=0.1} LOWMEM
cent: CENTER_OF_MULTICOLVAR DATA=trans1
# Calculate the phase field of the coordination
dens: MULTICOLVARDENS DATA=trans1 ORIGIN=cent DIR=xyz NBINS=30,30,30 BANDWIDTH=2.0,2.0,2.0
# Find the isocontour around the nucleus
FIND_SPHERICAL_CONTOUR GRID=dens CONTOUR=0.85 INNER_RADIUS=10.0 OUTER_RADIUS=40.0 FILE=mysurface.xyz UNITS=A P
6.32
FOURIER_TRANSFORM
Compute the Discrete Fourier Transform (DFT) by means of FFTW of data stored on a 2D grid.
This action can operate on any other action that outputs scalar data on a two-dimensional grid.
Up to now, even if the input data are purely real the action uses a complex DFT.
Just as a quick reference, given a 1D array X of size n, this action computes the vector Y given by
Yk =
n−1
X
Xj e2π jk
√
−1/n
.
j=0
Generated by Doxygen
6.32 FOURIER_TRANSFORM
397
This can be easily extended to more than one dimension. All the other details can be found at http://www.←fftw.org/doc/What-FFTW-Really-Computes.html#What-FFTW-Really-Computes.
The keyword "FOURIER_PARAMETERS" deserves just a note on the usage. This keyword specifies how the
Fourier transform will be normalized. The keyword takes two numerical parameters ( a, b) that define the normalization according to the following expression
1
n(1−a)/2
n−1
X
Xj e2πb jk
√
−1/n
j=0
The default values of these parameters are: a = 1 and b = 1.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the data should be collected and added to
the quantity being averaged
CLEAR
( default=0 ) the frequency with which to clear all the accumulated data. The
default value of 0 implies that all the data will be used and that the grid will never
be cleared
( default=true ) This controls how the data is normalized it can be set equal to
true, false or ndata. The differences between these options are explained in the
manual page for HISTOGRAM
NORMALIZATION
GRID
the action that creates the input grid you would like to use
FOURIER_PARAMETERS
( default=default ) what kind of normalization is applied to the output and if the
Fourier transform in FORWARD or BACKWARD. This keyword takes the form
FOURIER_PARAMETERS=A,B, where A and B can be 0, 1 or -1. The default
values are A=1 (no normalization at all) and B=1 (forward FFT). Other possible
choices for A are: A=-1: normalize by the number of data, A=0: normalize by the
square root of the number of data (one forward and followed by backward FFT
recover the original data).
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
LOGWEIGHTS
list of actions that calculates log weights that should be used to weight configurations
when calculating averages
CONCENTRATION
the concentration parameter for Von Mises-Fisher distributions
COMPONENT
if your input is a vector field use this to specify the component of the input vector field for
which you wish to use
FT_TYPE
choose what kind of data you want as output on the grid. Possible values are: ABS =
compute the complex modulus of Fourier coefficients (DEFAULT); NORM = compute the
norm (i.e. ABS∧ 2) of Fourier coefficients; COMPLEX = store the FFTW complex output
on the grid (as a vector).
Generated by Doxygen
398
Analysis
Examples
The following example tells Plumed to compute the complex 2D 'backward' Discrete Fourier Transform by taking the
data saved on a grid called 'density', and normalizing the output by √ 1
, where Nx and Ny are the number of
Nx Ny
data on the grid (it can be the case that Nx 6= Ny ):
BEGIN_PLUMED_FILE
FOURIER_TRANSFORM STRIDE=1 GRID=density FT_TYPE=complex FOURIER_PARAMETERS=0,-1 FILE=fourier.dat
6.33
GRID_TO_XYZ
Output the function on the grid to an xyz file
Compulsory keywords
GRID
the action that creates the grid you would like to output
STRIDE
( default=0 ) the frequency with which the grid should be output to the file. The default value of 0
ensures that the grid is only output at the end of the trajectory
FILE
( default=density ) the file on which to write the grid.
REPLICA
( default=0 ) the replicas for which you would like to output this information
UNITS
( default=PLUMED ) the units in which to print out the coordinates. PLUMED means internal PL←UMED units
Options
COMPONENT
if your input is a vector field use this to specify the component of the input vector field for which
you wish to output
PRECISION
The number of digits in trajectory file
Examples
6.34
INTEGRATE_GRID
Calculate the total integral of the function on the input grid
Compulsory keywords
Generated by Doxygen
6.35 INTERPOLATE_GRID
399
STRIDE
( default=1 ) the frequency with which the data should be collected and added to the
quantity being averaged
NORMALIZATION
GRID
( default=true ) This controls how the data is normalized it can be set equal to true, false
or ndata. The differences between these options are explained in the manual page for
HISTOGRAM
the action that creates the input grid you would like to use
CLEAR
( default=1 ) the frequency with which to clear all the accumulated data.
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
LOGWEIGHTS
list of actions that calculates log weights that should be used to weight configurations
when calculating averages
CONCENTRATION
the concentration parameter for Von Mises-Fisher distributions
COMPONENT
if your input is a vector field use this to specify the component of the input vector field for
which you wish to use
Examples
6.35
INTERPOLATE_GRID
Interpolate a smooth function stored on a grid onto a grid with a smaller grid spacing.
This action takes a function evaluated on a grid as input and can be used to interpolate the values of that function
on to a finer grained grid. The interpolation within this algorithm is done using splines.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the data should be collected and added to the
quantity being averaged
CLEAR
( default=0 ) the frequency with which to clear all the accumulated data. The default value
of 0 implies that all the data will be used and that the grid will never be cleared
NORMALIZATION
( default=true ) This controls how the data is normalized it can be set equal to true, false
or ndata. The differences between these options are explained in the manual page for
HISTOGRAM
the action that creates the input grid you would like to use
GRID
Options
Generated by Doxygen
400
Analysis
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
TIMINGS
( default=off ) output information on the timings of the various parts of the calculation
LOGWEIGHTS
list of actions that calculates log weights that should be used to weight configurations
when calculating averages
CONCENTRATION
the concentration parameter for Von Mises-Fisher distributions
COMPONENT
if your input is a vector field use this to specify the component of the input vector field for
which you wish to use
GRID_BIN
the number of bins for the grid
GRID_SPACING
the approximate grid spacing (to be used as an alternative or together with GRID_BIN)
Examples
The input below can be used to post process a trajectory. It calculates a HISTOGRAM as a function the distance
between atoms 1 and 2 using kernel density estimation. During the calculation the values of the kernels are evaluated at 100 points on a uniform grid between 0.0 and 3.0. Prior to outputting this function at the end of the simulation
this function is interpolated onto a finer grid of 200 points between 0.0 and 3.0.
BEGIN_PLUMED_FILE
x: DISTANCE ATOMS=1,2
hA1: HISTOGRAM ARG=x GRID_MIN=0.0 GRID_MAX=3.0 GRID_BIN=100 BANDWIDTH=0.1
ii: INTERPOLATE_GRID GRID=hA1 GRID_BIN=200
DUMPGRID GRID=ii FILE=histo.dat
6.36
COLLECT_FRAMES
This is part of the analysis module
This allows you to convert a trajectory and a dissimilarity matrix into a dissimilarity object
The data to analyze can be the output from another analysis algorithm
ATOMS
the atoms whose positions we are tracking for the purpose of analyzing the data
STRIDE
the frequency with which data should be stored for analysis. By default data is collected on every step
Compulsory keywords
CLEAR
( default=0 ) the frequency with which data should all be deleted and restarted
Options
Generated by Doxygen
6.37 EUCLIDEAN_DISSIMILARITIES
401
LOWMEM
( default=off ) lower the memory requirements
ARG
the input for this action is the scalar output from one or more other actions. The particular
scalars that you will use are referenced using the label of the action. If the label appears on
its own then it is assumed that the Action calculates a single scalar value. The value of this
scalar is thus used as the input to this new action. If ∗ or ∗.∗ appears the scalars calculated
by all the proceeding actions in the input file are taken. Some actions have multi-component
outputs and each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x component you
should use dist.x, if you wish to take all three components then use dist.∗.More information
on the referencing of Actions can be found in the section of the manual on the PLUMED
Getting Started. Scalar values can also be referenced using POSIX regular expressions as
detailed in the section on Regular Expressions. To use this feature you you must compile
PLUMED with the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
LOGWEIGHTS
list of actions that calculates log weights that should be used to weight configurations when
calculating averages
Examples
6.37
EUCLIDEAN_DISSIMILARITIES
This is part of the analysis module
Calculate the matrix of dissimilarities between a trajectory of atomic configurations.
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Alternatively data can be collected from the trajectory using
ATOMS
the list of atoms that you are going to use in the measure of distance that you are using. For more
information on how to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
METRIC
( default=EUCLIDEAN ) the method that you are going to use to measure the distances between points
Generated by Doxygen
402
Analysis
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
ARG
the input for this action is the scalar output from one or more other actions. The particular scalars
that you will use are referenced using the label of the action. If the label appears on its own then it
is assumed that the Action calculates a single scalar value. The value of this scalar is thus used as
the input to this new action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and each component of
the output has a specific label. For example a DISTANCE action labelled dist may have three
components x, y and z. To take just the x component you should use dist.x, if you wish to take all
three components then use dist.∗.More information on the referencing of Actions can be found in
the section of the manual on the PLUMED Getting Started. Scalar values can also be referenced
using POSIX regular expressions as detailed in the section on Regular Expressions. To use this
feature you you must compile PLUMED with the appropriate flag. You can use multiple instances
of this keyword i.e. ARG1, ARG2, ARG3...
Examples
6.38
PRINT_DISSIMILARITY_MATRIX
This is part of the analysis module
Print the matrix of dissimilarities between a trajectory of atomic configurations.
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
FILE
name of file on which to output the data
STRIDE
( default=0 ) the frequency with which to perform the required analysis and to output the data. The
default value of 0 tells plumed to use all the data
Options
Generated by Doxygen
6.40 LANDMARK_SELECT_FPS
403
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
FMT
the format to use for the output of numbers
Examples
6.39
READ_DISSIMILARITY_MATRIX
This is part of the analysis module
Read a matrix of dissimilarities between a trajectory of atomic configurations from a file.
Compulsory keywords
FILE
an input file containing the matrix of dissimilarities
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
WFILE
input file containing weights of points
Examples
6.40
LANDMARK_SELECT_FPS
This is part of the analysis module
Select a set of landmarks using farthest point sampling.
The data to analyze can be the output from another analysis algorithm
Generated by Doxygen
404
Analysis
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
NLANDMARKS
the number of landmarks that you would like to select
SEED
( default=1234 ) a random number seed
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
NOVORONOI
( default=off ) do not do a Voronoi analysis of the data to determine weights of final points
IGNORE_WEIGHTS
( default=off ) ignore the weights in the underlying analysis object
Examples
6.41
LANDMARK_SELECT_RANDOM
This is part of the analysis module
Select a random set of landmarks from a large set of configurations.
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
NLANDMARKS
the number of landmarks that you would like to select
SEED
( default=1234 ) a random number seed
Options
Generated by Doxygen
6.43 LANDMARK_SELECT_STRIDE
405
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
NOVORONOI
( default=off ) do not do a Voronoi analysis of the data to determine weights of final points
IGNORE_WEIGHTS
( default=off ) ignore the weights in the underlying analysis object
Examples
6.42
LANDMARK_SELECT_STAGED
This is part of the analysis module
Select a set of landmarks using the staged algorithm.
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
NLANDMARKS
the number of landmarks that you would like to select
GAMMA
the gamma parameter to be used in weights
SEED
( default=1234 ) a random number seed
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
NOVORONOI
( default=off ) do not do a Voronoi analysis of the data to determine weights of final points
IGNORE_WEIGHTS
( default=off ) ignore the weights in the underlying analysis object
Examples
6.43
LANDMARK_SELECT_STRIDE
Generated by Doxygen
406
Analysis
This is part of the analysis module
Select every k th landmark from the trajectory.
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
NLANDMARKS
the number of landmarks that you would like to select
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
NOVORONOI
( default=off ) do not do a Voronoi analysis of the data to determine weights of final points
IGNORE_WEIGHTS
( default=off ) ignore the weights in the underlying analysis object
Examples
6.44
RESELECT_LANDMARKS
This is part of the analysis module
This allows us to use one measure in landmark selection and a different measure in dimensionality reduction
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
Generated by Doxygen
6.45 CLASSICAL_MDS
LANDMARKS
407
the action that selects the landmarks that you want to reselect using this action
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
NOVORONOI
( default=off ) do not do a Voronoi analysis of the data to determine weights of final points
IGNORE_WEIGHTS
( default=off ) ignore the weights in the underlying analysis object
Examples
6.45
CLASSICAL_MDS
This is part of the dimred module
It is only available if you configure PLUMED with ./configure –enable-modules=dimred . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Create a low-dimensional projection of a trajectory using the classical multidimensional scaling algorithm.
Multidimensional scaling (MDS) is similar to what is done when you make a map. You start with distances between
London, Belfast, Paris and Dublin and then you try to arrange points on a piece of paper so that the (suitably scaled)
distances between the points in your map representing each of those cities are related to the true distances between
the cities. Stating this more mathematically MDS endeavors to find an isometry between points distributed in
a high-dimensional space and a set of points distributed in a low-dimensional plane. In other words, if we have
M D-dimensional points, X, and we can calculate dissimilarities between pairs them, Dij , we can, with an MDS
calculation, try to create M projections, x, of the high dimensionality points in a d-dimensional linear space by trying
to arrange the projections so that the Euclidean distances between pairs of them, dij , resemble the dissimilarities
between the high dimensional points. In short we minimize:
χ2 =
X
(Dij − dij )
2
i6=j
where Dij is the distance between point X i and point X j and dij is the distance between the projection of X i , xi ,
and the projection of X j , xj . A tutorial on this approach can be used to analyze simulations can be found in the
tutorial Belfast tutorial: Adaptive variables II and in the following short video.
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Generated by Doxygen
408
Analysis
Quantity
Description
coord
the low-dimensional projections of the various input configurations
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
NLOW_DIM
number of low-dimensional coordinates required
Generated by Doxygen
6.45 CLASSICAL_MDS
409
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
Examples
The following command instructs plumed to construct a classical multidimensional scaling projection of a trajectory.
The RMSD distance between atoms 1-256 have moved is used to measure the distances in the high-dimensional
space.
BEGIN_PLUMED_FILE
CLASSICAL_MDS ...
ATOMS=1-256
METRIC=OPTIMAL-FAST
NLOW_DIM=2
OUTPUT_FILE=rmsd-embed
... CLASSICAL_MDS
The following section is for people who are interested in how this method works in detail. A solid understanding of
this material is not necessary to use MDS.
6.45.1
Method of optimization
The stress function can be minimized using a standard optimization algorithm such as conjugate gradients or steepest descent. However, it is more common to do this minimization using a technique known as classical scaling.
Classical scaling works by recognizing that each of the distances $D_{ij}$ in the above sum can be written as:
2
Dij
=
X
α
(Xαi − Xαj )2 =
X
(Xαi )2 + (Xαj )2 − 2Xαi Xαj
α
We can use this expression and matrix algebra to calculate multiple distances at once. For instance if we have three
points, X, we can write distances between them as:
0 d212 d213
D2 (X) = d212 0 d223
d213 d223 0
1 2
2 2
1 2
1 2
1 2
X (Xα ) (Xα ) (Xα )
X (Xα ) (Xα )
2
2
2
2
2
2
1
2
(Xα ) (Xα ) (Xα ) +
(Xα ) (Xα2 )2
=
3
2
3
2
3
2
α
α
(Xα ) (Xα ) (Xα )
(Xα1 )2 (Xα2 )2
X
= c1T + 1cT − 2
xa xTa = c1T + 1cT − 2XXT
1 1
(Xα3 )2
X Xα Xα
Xα2 Xα1
(Xα3 )2 − 2
3 2
α
(Xα )
Xα1 Xα3
Xα1 Xα2
Xα2 Xα2
Xα3 Xα2
α
This last equation can be extended to situations when we have more than three points. In it X is a matrix that has
one high-dimensional point on each of its rows and XT is its transpose. 1 is an M × 1 vector of ones and c is a
vector with components given by:
Generated by Doxygen
Xα1 Xα3
Xα2 Xα3
Xα3 Xα3
410
Analysis
ci =
X
(xiα )2
α
These quantities are the diagonal elements of XXT , which is a dot product or Gram Matrix that contains the dot
product of the vector Xi with the vector Xj in element i, j .
In classical scaling we introduce a centering matrix J that is given by:
J=I−
1
11T
M
where I is the identity. Multiplying the equations above from the front and back by this matrix and a factor of a − 12
gives:
1
− JD2 (X)J
2
=
=
=
1
− J(c1T + 1cT − 2XXT )J
2
1
1
1
− Jc1T J − J1cT J + J(2XXT )J
2
2
2
JXXT J = XXT
The fist two terms in this expression disappear because 1T J = J1 = 0, where 0 is a matrix containing all zeros.
In the final step meanwhile we use the fact that the matrix of squared distances will not change when we translate
all the points. We can thus assume that the mean value, µ, for each of the components, α:
µα =
N
1 X i
X
M i=1 α
is equal to 0 so the columns of X add up to 0. This in turn means that each of the columns of XXT adds up to
zero, which is what allows us to write JXXT J = XXT .
The matrix of squared distances is symmetric and positive-definite we can thus use the spectral decomposition to
decompose it as:
Φ = VΛVT
Furthermore, because the matrix we are diagonalizing, XXT , is the product of a matrix and its transpose we can
use this decomposition to write:
1
X = VΛ 2
Much as in PCA there are generally a small number of large eigenvalues in Λ and many small eigenvalues. We can
safely use only the large eigenvalues and their corresponding eigenvectors to express the relationship between the
coordinates X. This gives us our set of low-dimensional projections.
This derivation makes a number of assumptions about the how the low dimensional points should best be arranged
to minimize the stress. If you use an interactive optimization algorithm such as SMACOF you may thus be able to find
a better (lower-stress) projection of the points. For more details on the assumptions made see this website.
6.46
OUTPUT_PCA_PROJECTION
Generated by Doxygen
6.47 PCA
411
This is part of the dimred module
It is only available if you configure PLUMED with ./configure –enable-modules=dimred . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
This is used to output the projection calculated by principle component analysis
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
FILE
the name of the file to output to
STRIDE
( default=0 ) the frequency with which to perform the required analysis and to output the data. The
default value of 0 tells plumed to use all the data
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
FMT
the format to use in the output file
Examples
6.47
PCA
This is part of the dimred module
It is only available if you configure PLUMED with ./configure –enable-modules=dimred . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Perform principal component analysis (PCA) using either the positions of the atoms a large number of collective
variables as input.
Principal component analysis is a statistical technique that uses an orthogonal transformation to convert a set of
observations of poorly correlated variables into a set of linearly uncorrelated variables. You can read more about
the specifics of this technique here: https://en.wikipedia.org/wiki/Principal_component_←-
analysis
Generated by Doxygen
412
Analysis
When used with molecular dynamics simulations a set of frames taken from the trajectory, {Xi }, or the values
of a number of collective variables which are calculated from the trajectory frames are used as input. In this
second instance your input to the PCA analysis algorithm is thus a set of high-dimensional vectors of collective
variables. However, if collective variables are calculated from the positions of the atoms or if the positions are
used directly the assumption is that this input trajectory is a set of poorly correlated (high-dimensional) vectors.
After principal component analysis has been performed the output is a set of orthogonal vectors that describe the
directions in which the largest motions have been seen. In other words, principal component analysis provides a
method for lowering the dimensionality of the data contained in a trajectory. These output directions are some linear
combination of the x, y and z positions if the positions were used as input or some linear combination of the input
collective variables if a high-dimensional vector of collective variables was used as input.
As explained on the Wikipedia page you must calculate the average and covariance for each of the input coordinates.
In other words, you must calculate the average structure and the amount the system fluctuates around this average
structure. The problem in doing so when the x, y and z coordinates of a molecule are used as input is that the
majority of the changes in the positions of the atoms comes from the translational and rotational degrees of freedom
of the molecule. The first six principal components will thus, most likely, be uninteresting. Consequently, to remedy
this problem PLUMED provides the functionality to perform an RMSD alignment of the all the structures to be
analyzed to the first frame in the trajectory. This can be used to effectively remove translational and/or rotational
motions from consideration. The resulting principal components thus describe vibrational motions of the molecule.
If you wish to calculate the projection of a trajectory on a set of principal components calculated from this PCA
action then the output can be used as input for the PCAVARS action.
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
coord
the low-dimensional projections of the various input configurations
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
Generated by Doxygen
6.47 PCA
413
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Alternatively data can be collected from the trajectory using
ATOMS
the list of atoms that you are going to use in the measure of distance that you are using. For more
information on how to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
NLOW_DIM
number of low-dimensional coordinates required
METRIC
( default=EUCLIDEAN ) the method that you are going to use to measure the distances between
points
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
Generated by Doxygen
414
Analysis
ARG
the input for this action is the scalar output from one or more other actions. The particular scalars
that you will use are referenced using the label of the action. If the label appears on its own then it
is assumed that the Action calculates a single scalar value. The value of this scalar is thus used as
the input to this new action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and each component of
the output has a specific label. For example a DISTANCE action labelled dist may have three
components x, y and z. To take just the x component you should use dist.x, if you wish to take all
three components then use dist.∗.More information on the referencing of Actions can be found in
the section of the manual on the PLUMED Getting Started. Scalar values can also be referenced
using POSIX regular expressions as detailed in the section on Regular Expressions. To use this
feature you you must compile PLUMED with the appropriate flag. You can use multiple instances
of this keyword i.e. ARG1, ARG2, ARG3...
Examples
The following input instructs PLUMED to perform a principal component analysis in which the covariance matrix is
calculated from changes in the positions of the first 22 atoms. The TYPE=OPTIMAL instruction ensures that translational and rotational degrees of freedom are removed from consideration. The first two principal components will
be output to a file called PCA-comp.pdb. Trajectory frames will be collected on every step and the PCA calculation
will be performed at the end of the simulation.
BEGIN_PLUMED_FILE
PCA METRIC=OPTIMAL ATOMS=1-22 STRIDE=1 NLOW_DIM=2 OFILE=PCA-comp.pdb
The following input instructs PLUMED to perform a principal component analysis in which the covariance matrix
is calculated from changes in the six distances seen in the previous lines. Notice that here the TYPE=EUCLID←EAN keyword is used to indicate that no alignment has to be done when calculating the various elements of the
covariance matrix from the input vectors. In this calculation the first two principal components will be output to a
file called PCA-comp.pdb. Trajectory frames will be collected every five steps and the PCA calculation is performed
every 1000 steps. Consequently, if you run a 2000 step simulation the PCA analysis will be performed twice. The
REWEIGHT_BIAS keyword in this input tells PLUMED that rather that ascribing a weight of one to each of the
frames when calculating averages and covariance matrices a reweighting should be performed based and each
frames' weight in these calculations should be determined based on the current value of the instantaneous bias
(see REWEIGHT_BIAS).
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=1,2
d2: DISTANCE ATOMS=1,3
d3: DISTANCE ATOMS=1,4
d4: DISTANCE ATOMS=2,3
d5: DISTANCE ATOMS=2,4
d6: DISTANCE ATOMS=3,4
PCA ARG=d1,d2,d3,d4,d5,d6 METRIC=EUCLIDEAN STRIDE=5 RUN=1000 NLOW_DIM=2 REWEIGHT_BIAS OFILE=PCA-comp.pdb
6.48
PROJECT_ALL_ANALYSIS_DATA
This is part of the dimred module
It is only available if you configure PLUMED with ./configure –enable-modules=dimred . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Generated by Doxygen
6.48 PROJECT_ALL_ANALYSIS_DATA
415
Find projections of all non-landmark points using the embedding calculated by a dimensionality reduction optimization calculation.
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
coord
the low-dimensional projections of the various input configurations
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
Generated by Doxygen
416
Analysis
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
PROJECTION
the projection that you wish to generate out-of-sample projections with
CGTOL
( default=1E-6 ) the tolerance for the conjugate gradient optimization
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
Examples
6.49
SKETCHMAP_CONJGRAD
This is part of the dimred module
It is only available if you configure PLUMED with ./configure –enable-modules=dimred . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Optimize the sketch-map stress function using conjugate gradients.
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
coord
the low-dimensional projections of the various input configurations
In addition the following quantities can be calculated by employing the keywords listed below
Generated by Doxygen
6.49 SKETCHMAP_CONJGRAD
417
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
HIGH_DIM_FUNCTION
( default=as in input action ) the parameters of the switching function in the high
dimensional space
LOW_DIM_FUNCTION
( default=as in input action ) the parameters of the switching function in the low dimensional space
MIXPARAM
( default=0.0 ) the amount of the pure distances to mix into the stress function
CGTOL
( default=1E-6 ) the tolerance for the conjugate gradient minimization
Generated by Doxygen
418
Analysis
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
Examples
6.50
SKETCHMAP_POINTWISE
This is part of the dimred module
It is only available if you configure PLUMED with ./configure –enable-modules=dimred . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Optimize the sketch-map stress function using a pointwise global optimization algorithm.
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
coord
the low-dimensional projections of the various input configurations
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
Generated by Doxygen
6.50 SKETCHMAP_POINTWISE
419
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
HIGH_DIM_FUNCTION
( default=as in input action ) the parameters of the switching function in the high
dimensional space
LOW_DIM_FUNCTION
( default=as in input action ) the parameters of the switching function in the low dimensional space
MIXPARAM
( default=0.0 ) the amount of the pure distances to mix into the stress function
NCYCLES
( default=5 ) the number of cycles of global optimization to attempt
CGTOL
( default=1E-6 ) the tolerance for the conjugate gradient minimization
BUFFER
( default=1.1 ) grid extent for search is (max projection - minimum projection) multiplied by this value
CGRID_SIZE
( default=10 ) number of points to use in each grid direction
FGRID_SIZE
( default=0 ) interpolate the grid onto this number of points – only works in 2D
Options
Generated by Doxygen
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
420
Analysis
Examples
6.51
SKETCHMAP_READ
This is part of the dimred module
It is only available if you configure PLUMED with ./configure –enable-modules=dimred . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Read in a sketch-map projection from an input file
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
coord
the low-dimensional projections of the various input configurations
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
Generated by Doxygen
6.52 SKETCHMAP_SMACOF
421
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
Compulsory keywords
HIGH_DIM_FUNCTION
( default=as in input action ) the parameters of the switching function in the high
dimensional space
LOW_DIM_FUNCTION
( default=as in input action ) the parameters of the switching function in the low dimensional space
MIXPARAM
( default=0.0 ) the amount of the pure distances to mix into the stress function
TYPE
( default=OPTIMAL-FAST ) the manner in which distances are calculated. More
information on the different metrics that are available in PLUMED can be found in the
section of the manual on Distances from reference configurations
REFERENCE
the file containing the sketch-map projection
PROPERTY
the property to be used in the index. This should be in the REMARK of the reference
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
DISABLE_CHECKS
( default=off ) disable checks on reference input structures.
Examples
6.52
SKETCHMAP_SMACOF
This is part of the dimred module
It is only available if you configure PLUMED with ./configure –enable-modules=dimred . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Optimize the sketch-map stress function using the SMACOF algorithm.
Generated by Doxygen
422
Analysis
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
coord
the low-dimensional projections of the various input configurations
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The data to analyze can be the output from another analysis algorithm
Generated by Doxygen
6.53 SKETCH_MAP
423
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
HIGH_DIM_FUNCTION
( default=as in input action ) the parameters of the switching function in the high
dimensional space
LOW_DIM_FUNCTION
( default=as in input action ) the parameters of the switching function in the low
dimensional space
MIXPARAM
( default=0.0 ) the amount of the pure distances to mix into the stress function
SMACOF_TOL
( default=1E-4 ) the tolerance for each SMACOF cycle
SMACOF_MAXCYC
( default=1000 ) maximum number of optimization cycles for SMACOF algorithm
SMAP_TOL
( default=1E-4 ) the tolerance for sketch-map
SMAP_MAXCYC
( default=100 ) maximum number of optimization cycles for iterative sketch-map algorithm
REGULARISE_PARAM
( default=0.001 ) this is used to ensure that we don't divide by zero when updating
weights
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
Examples
6.53
SKETCH_MAP
This is part of the dimred module
It is only available if you configure PLUMED with ./configure –enable-modules=dimred . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
This can be used to output the data that has been stored in an Analysis object.
Compulsory keywords
NLOW_DIM
MATRIX
Generated by Doxygen
the dimension of the low dimensional space in which the projections will be constructed
the matrix of distances between points that you want to reproduce in your sketch-map
projection
424
Analysis
HIGH_DIM_FUNCTION
the parameters of the switching function in the high dimensional space
LOW_DIM_FUNCTION
the parameters of the switching function in the low dimensional space
ANNEAL_RATE
( default=0.5 ) the rate at which to do the annealing
ANNEAL_STEPS
( default=10 ) the number of steps of annealing to do
CGTOL
( default=1E-6 ) the tolerance for the conjugate gradient minimization
NCYCLES
( default=5 ) the number of cycles of global optimization to attempt
BUFFER
( default=1.1 ) grid extent for search is (max projection - minimum projection) multiplied by this value
CGRID_SIZE
( default=10 ) number of points to use in each grid direction
FGRID_SIZE
( default=0 ) interpolate the grid onto this number of points – only works in 2D
Examples
6.54
SMACOF_MDS
This is part of the dimred module
It is only available if you configure PLUMED with ./configure –enable-modules=dimred . Furthermore,
this feature is still being developed so take care when using it and report any problems on the mailing
list.
Optimize the multidimensional scaling stress function using the SMACOF algorithm.
Description of components
By default the value of the calculated quantity can be referenced elsewhere in the input file by using the label of the
action. Alternatively this Action can be used to calculate the following quantities by employing the keywords listed
below. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and
the name of the quantity required from the list below.
Quantity
Description
coord
the low-dimensional projections of the various input configurations
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
gradient
GRADIENT
the gradient
vmean
VMEAN
the norm of the mean vector. The output component can be referred to elsewhere
in the input file by using the label.vmean
vsum
VSUM
the norm of sum of vectors. The output component can be referred to elsewhere
in the input file by using the label.vsum
spath
SPATH
the position on the path
gspath
GPATH
the position on the path calculated using trigonometry
gzpath
GPATH
the distance from the path calculated using trigonometry
zpath
ZPATH
the distance from the path
Generated by Doxygen
6.54 SMACOF_MDS
425
altmin
ALT_MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
between
BETWEEN
the number/fraction of values within a certain range. This is calculated using one
of the formula described in the description of the keyword so as to make it continuous. You can calculate this quantity multiple times using different parameters.
highest
HIGHEST
the lowest of the quantities calculated by this action
lessthan
LESS_THAN
the number of values less than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
lowest
LOWEST
the lowest of the quantities calculated by this action
max
MAX
the maximum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
mean
MEAN
the mean value. The output component can be referred to elsewhere in the input
file by using the label.mean
min
MIN
the minimum value. This is calculated using the formula described in the description of the keyword so as to make it continuous.
moment
MOMENTS
the central moments of the distribution of values. The second moment would
be referenced elsewhere in the input file using label.moment-2, the third as
label.moment-3, etc.
morethan
MORE_THAN
the number of values more than a target value. This is calculated using one of the
formula described in the description of the keyword so as to make it continuous.
You can calculate this quantity multiple times using different parameters.
sum
SUM
the sum of values
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
SMACOF_TOL
( default=1E-4 ) tolerance for the SMACOF optimization algorithm
SMACOF_MAXCYC
( default=1000 ) maximum number of optimization cycles for SMACOF algorithm
Options
Examples
Generated by Doxygen
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
426
6.55
Analysis
OUTPUT_ANALYSIS_DATA_TO_COLVAR
This is part of the analysis module
This can be used to output the data that has been stored in an Analysis object.
The most useful application of this method is to output all projections of all the points that were stored in an analysis
object that performs some form of dimensionality reduction. If you use the USE_DIMRED_DATA_FROM option
below projections of all the stored points will be output to a file. The positions of these projections will be calculated
using that dimensionality reduction algorithms out-of-sample extension algorithm.
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
FILE
the name of the file to output to
REPLICA
( default=0 ) the replicas for which you would like to output this information
STRIDE
( default=0 ) the frequency with which to perform the required analysis and to output the data. The
default value of 0 tells plumed to use all the data
Options
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
ARG
the input for this action is the scalar output from one or more other actions. The particular scalars
that you will use are referenced using the label of the action. If the label appears on its own then it
is assumed that the Action calculates a single scalar value. The value of this scalar is thus used as
the input to this new action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and each component of
the output has a specific label. For example a DISTANCE action labelled dist may have three
components x, y and z. To take just the x component you should use dist.x, if you wish to take all
three components then use dist.∗.More information on the referencing of Actions can be found in
the section of the manual on the PLUMED Getting Started. Scalar values can also be referenced
using POSIX regular expressions as detailed in the section on Regular Expressions. To use this
feature you you must compile PLUMED with the appropriate flag. You can use multiple instances
of this keyword i.e. ARG1, ARG2, ARG3...
FMT
the format to output the data using
Examples
Generated by Doxygen
6.56 OUTPUT_ANALYSIS_DATA_TO_PDB
6.56
427
OUTPUT_ANALYSIS_DATA_TO_PDB
This is part of the analysis module
This can be used to output the data that has been stored in an Analysis object.
The data to analyze can be the output from another analysis algorithm
USE_OUTPUT_DATA_FROM
use the output of the analysis performed by this object as input to your new
analysis object
Compulsory keywords
FILE
the name of the file to output to
STRIDE
( default=0 ) the frequency with which to perform the required analysis and to output the data. The
default value of 0 tells plumed to use all the data
Options
Examples
Generated by Doxygen
SERIAL
( default=off ) do the calculation in serial. Do not use MPI
LOWMEM
( default=off ) lower the memory requirements
FMT
the format to use in the output file
428
Analysis
Generated by Doxygen
Chapter 7
Bias
PLUMED allows you to run a number of enhanced sampling algorithms. The list of enhanced sampling algorithms
contained in PLUMED is as follows:
ABMD
Adds a ratchet-and-pawl like restraint on one or more variables.
BIASVALUE
EXTENDED_LAGRANGIAN
Takes the value of one variable and use it as a bias
Add extended Lagrangian.
EXTERNAL
Calculate a restraint that is defined on a grid that is read during start up
LOWER_WALLS
Defines a wall for the value of one or more collective variables, which limits the
region of the phase space accessible during the simulation.
MAXENT
Add a linear biasing potential on one or more variables fi (x) satisfying the maximum entropy principle as proposed in Ref. [34] .
METAD
Used to performed metadynamics on one or more collective variables.
MOVINGRESTRAINT
Add a time-dependent, harmonic restraint on one or more variables.
PBMETAD
Used to performed Parallel Bias metadynamics.
RESTRAINT
UPPER_WALLS
Adds harmonic and/or linear restraints on one or more variables.
Defines a wall for the value of one or more collective variables, which limits the
region of the phase space accessible during the simulation.
In addition to the keywords above, by enabling optional modules you can access to the following keywords:
CALIBER
(from PLUMED-ISDB module) Add a time-dependent, harmonic restraint on one
or more variables.This allows implementing a maximum caliber restraint on one
or more experimental time series by replica-averaged restrained simulations.See
[35] .
DRR
(from Extended-System Adaptive Biasing Force module) Used to performed
extended-system adaptive biasing force(eABF) [36] method on one or more collective variables. This method is also called dynamic reference restraining(DRR)
[37] .
EDS
(from Experiment Directed Simulation module) Add a linear bias on a set of observables.
(from Logarithmic Mean Force Dynamics module) Used to perform LogMFD,
LogPD, and TAMD/d-AFED.
LOGMFD
MAZE_OPTIMIZER_BIAS
(from MAZE module)
METAINFERENCE
(from PLUMED-ISDB module) Calculates the Metainference energy for a set of
experimental data.
RESCALE
(from PLUMED-ISDB module) Scales the value of an another action, being a
Collective Variable or a Bias.
430
Bias
VES_DELTA_F
(from Variationally Enhanced Sampling (VES code) module) Implementation of
VES ∆F method [38] (step two only).
VES_LINEAR_EXPANSION
(from Variationally Enhanced Sampling (VES code) module) Linear basis set expansion bias.
Methods, such as METAD or PBMETAD, that work by introducing a history dependent bias can be restarted using
the RESTART keyword
7.1
ABMD
This is part of the bias module
Adds a ratchet-and-pawl like restraint on one or more variables.
This action can be used to evolve a system towards a target value in CV space using an harmonic potential moving
with the thermal fluctuations of the CV [39] [40] [41]. The biasing potential in this method is as follows:
V (ρ(t)) =
K
2
2
(ρ(t) − ρm (t)) ,
0,
ρ(t) > ρm (t)
ρ(t) ≤ ρm (t),
where
ρ(t) = (CV (t) − T O)
2
and
ρm (t) = min0≤τ ≤t ρ(τ ) + η(t).
The method is based on the introduction of a biasing potential which is zero when the system is moving towards the
desired arrival point and which damps the fluctuations when the system attempts to move in the opposite direction.
As in the case of the ratchet and pawl system, propelled by thermal motion of the solvent molecules, the biasing
potential does not exert work on the system. η(t) is an additional white noise acting on the minimum position of the
bias.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
force2
the instantaneous value of the squared force due to this bias potential
_min
one or multiple instances of this quantity can be referenced elsewhere in the input file. These
quantities will be named with the arguments of the bias followed by the character string _min. These
quantities tell the user the minimum value assumed by rho_m(t).
Generated by Doxygen
7.2 BIASVALUE
431
Compulsory keywords
TO
The array of target values
KAPPA
The array of force constants.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
MIN
Array of starting values for the bias (set rho_m(t), otherwise it is set using the
current value of ARG)
NOISE
Array of white noise intensities (add a temperature to the ABMD)
SEED
Array of seeds for the white noise (add a temperature to the ABMD)
Examples
The following input sets up two biases, one on the distance between atoms 3 and 5 and another on the distance
between atoms 2 and 4. The two target values are defined using TO and the two strength using KAPPA. The total
energy of the bias is printed.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
ABMD ARG=d1,d2 TO=1.0,1.5 KAPPA=5.0,5.0 LABEL=abmd
PRINT ARG=abmd.bias,abmd.d1_min,abmd.d2_min
7.2
BIASVALUE
This is part of the bias module
Takes the value of one variable and use it as a bias
Generated by Doxygen
432
Bias
This is the simplest possible bias: the bias potential is equal to a collective variable. It is useful to create custom
biasing potential, e.g. applying a function (see Functions) to some collective variable then using the value of this
function directly as a bias.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
_bias
one or multiple instances of this quantity can be referenced elsewhere in the input file. these quantities will named with the arguments of the bias followed by the character string _bias. These quantities tell the user how much the bias is due to each of the colvars.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
The following input tells plumed to use the value of the distance between atoms 3 and 5 and the value of the distance
between atoms 2 and 4 as biases. It then tells plumed to print the energy of the restraint
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=3,6 LABEL=d2
BIASVALUE ARG=d1,d2 LABEL=b
PRINT ARG=d1,d2,b.d1,b.d2
Another thing one can do is asking one system to follow a circle in sin/cos according a time dependence
Generated by Doxygen
7.3 EXTENDED_LAGRANGIAN
433
BEGIN_PLUMED_FILE
t: TIME
# this just print cos and sin of time
cos: MATHEVAL ARG=t VAR=t FUNC=cos(t) PERIODIC=NO
sin: MATHEVAL ARG=t VAR=t FUNC=sin(t) PERIODIC=NO
c1: COM ATOMS=1,2
c2: COM ATOMS=3,4
d: DISTANCE COMPONENTS ATOMS=c1,c2
PRINT ARG=t,cos,sin,d.x,d.y,d.z STRIDE=1 FILE=colvar FMT=%8.4f
# this calculates sine and cosine of a projected component of distance
mycos: MATHEVAL ARG=d.x,d.y VAR=x,y
FUNC=x/sqrt(x*x+y*y) PERIODIC=NO
mysin: MATHEVAL ARG=d.x,d.y VAR=x,y
FUNC=y/sqrt(x*x+y*y) PERIODIC=NO
# this creates a moving spring so that the system follows a circle-like dynamics
# but it is not a bias, it is a simple value now
vv1: MATHEVAL ARG=mycos,mysin,cos,sin VAR=mc,ms,c,s FUNC=100*((mc-c)^2+(ms-s)^2) PERIODIC=NO
# this takes the value calculated with matheval and uses as a bias
cc: BIASVALUE ARG=vv1
# some printout
PRINT ARG=t,cos,sin,d.x,d.y,d.z,mycos,mysin,cc.bias.vv1 STRIDE=1 FILE=colvar FMT=%8.4f
7.3
EXTENDED_LAGRANGIAN
Add extended Lagrangian.
This action can be used to create fictitious collective variables coupled to the real ones. Given xi the ith argument
of this bias potential, potential and kinetic contributions are added to the energy of the system as
V =
X ki
i
2
(xi − si )2 +
X ṡ2
i
2m
i
i
.
The resulting potential is thus similar to a RESTRAINT, but the restraint center moved with time following Hamiltonian dynamics with mass mi .
This bias potential accepts thus vectorial keywords (one element per argument) to define the coupling constant
τ 2
(KAPPA) and a relaxation time tau (TAU). The mass is them computed as m = k( 2π
) .
Notice that this action creates several components. The ones named XX_fict are the fictitious coordinates. It is
possible to add further forces on them by means of other bias potential, e.g. to obtain an indirect METAD as in [42]
. Also notice that the velocities of the fictitious coordinates are reported (XX_vfict). However, printed velocities are
the ones at the previous step.
It is also possible to provide a non-zero friction (one value per component). This is then used to implement a
Langevin thermostat, so as to implement TAMD/dAFED method [43] [44] . Notice that here a massive Langevin
thermostat is used, whereas usually TAMD employs an overamped Langevin dynamics and dAFED a Gaussian
thermostat.
Warning
The bias potential is reported in the component bias. Notice that this bias potential, although formally compatible with replica exchange framework, probably does not work as expected in that case. Indeed, since
fictitious coordinates are not swapped upon exchange, acceptace can be expected to be extremely low unless
(by chance) two neighboring replicas have the fictitious variables located properly in space.
RESTART is not properly supported by this action. Indeed, at every start the postion of the fictitious variable
is reset to the value of the real variable, and its velocity is set to zero. This is not expected to introduce big
errors, but certainly is introducing a small inconsistency between a single long run and many shorter runs.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Generated by Doxygen
434
Bias
Quantity
Description
bias
the instantaneous value of the bias potential
_fict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These
quantities will named with the arguments of the bias followed by the character string _tilde. It is
possible to add forces on these variable.
_vfict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These
quantities will named with the arguments of the bias followed by the character string _tilde. It is NOT
possible to add forces on these variable.
Compulsory keywords
KAPPA
TAU
FRICTION
specifies that the restraint is harmonic and what the values of the force constants on each of the
variables are
specifies that the restraint is harmonic and what the values of the force constants on each of the
variables are
( default=0.0 ) add a friction to the variable
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
TEMP
the system temperature - needed when FRICTION is present. If not provided
will be taken from MD code (if available)
Examples
The following input tells plumed to perform a metadynamics with an extended Lagrangian on two torsional angles.
BEGIN_PLUMED_FILE
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
ex: EXTENDED_LAGRANGIAN ARG=phi,psi KAPPA=20,20.0 TAU=0.1,0.1
METAD ARG=ex.phi_fict,ex.psi_fict PACE=100 SIGMA=0.35,0.35 HEIGHT=0.1
# monitor the two variables
PRINT STRIDE=10 ARG=phi,psi,ex.phi_fict,ex.psi_fict FILE=COLVAR
Generated by Doxygen
7.4 EXTERNAL
435
The following input tells plumed to perform a TAMD (or dAFED) calculation on two torsional angles, keeping the two
variables at a fictitious temperature of 3000K with a Langevin thermostat with friction 10
BEGIN_PLUMED_FILE
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
ex: EXTENDED_LAGRANGIAN ARG=phi,psi KAPPA=20,20.0 TAU=0.1,0.1 FRICTION=10,10 TEMP=3000
# monitor the two variables
PRINT STRIDE=10 ARG=phi,psi,ex.phi_fict,ex.psi_fict FILE=COLVAR
7.4
EXTERNAL
This is part of the bias module
Calculate a restraint that is defined on a grid that is read during start up
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
Compulsory keywords
FILE
the name of the file containing the external potential.
SCALE
( default=1.0 ) a factor that multiplies the external potential, useful to invert free energies
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOSPLINE
( default=off ) specifies that no spline interpolation is to be used when calculating the energy and forces due to the external potential
SPARSE
( default=off ) specifies that the external potential uses a sparse grid
Generated by Doxygen
436
ARG
Bias
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
The following is an input for a calculation with an external potential that is defined in the file bias.dat and that acts
on the distance between atoms 3 and 5.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
EXTERNAL ARG=d1 FILE=bias.dat LABEL=external
The header in the file bias.dat should read:
#!
#!
#!
#!
#!
FIELDS d1 external.bias der_d1
SET min_d1 0.0
SET max_d1 1.0
SET nbins_d1 100
SET periodic_d1 false
This should then be followed by the value of the potential and its derivative at 100 equally spaced points along the
distance between 0 and 1.
You can also include grids that are a function of more than one collective variable. For instance the following would
be the input for an external potential acting on two torsional angles:
BEGIN_PLUMED_FILE
TORSION ATOMS=4,5,6,7 LABEL=t1
TORSION ATOMS=6,7,8,9 LABEL=t2
EXTERNAL ARG=t1,t2 FILE=bias.dat LABEL=ext
The header in the file bias.dat for this calculation would read:
#!
#!
#!
#!
#!
#!
#!
#!
#!
FIELDS t1 t2 ext.bias der_t1 der_t2
SET min_t1 -pi
SET max_t1 +pi
SET nbins_t1 100
SET periodic_t1 true
SET min_t2 -pi
SET max_t2 +pi
SET nbins_t2 100
SET periodic_t2 true
This would be then followed by 100 blocks of data. In the first block of data the value of t1 (the value in the first
column) is kept fixed and the value of the function is given at 100 equally spaced values for t2 between −pi and
2pi
+pi. In the second block of data t1 is fixed at −pi + 100
and the value of the function is given at 100 equally spaced
values for t2 between −pi and +pi. In the third block of data the same is done but t1 is fixed at −pi +
on until you get to the one hundredth block of data where t1 is fixed at +pi.
4pi
100
and so
Please note the order that the order of arguments in the plumed.dat file must be the same as the order of arguments
in the header of the grid file.
Generated by Doxygen
7.5 LOWER_WALLS
7.5
437
LOWER_WALLS
This is part of the bias module
Defines a wall for the value of one or more collective variables, which limits the region of the phase space accessible
during the simulation.
The restraining potential starts acting on the system when the value of the CV is greater (in the case of UPPER←_WALLS) or lower (in the case of LOWER_WALLS) than a certain limit ai (AT) minus an offset oi (OFFSET). The
expression for the bias due to the wall is given by:
P
i
ki ((xi − ai + oi )/si )ei
ki (KAPPA) is an energy constant in internal unit of the code, si (EPS) a rescaling factor and ei (EXP) the exponent
determining the power law. By default: EXP = 2, EPS = 1.0, OFFSET = 0.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
force2
the instantaneous value of the squared force due to this bias potential
Compulsory keywords
AT
the positions of the wall. The a_i in the expression for a wall.
KAPPA
the force constant for the wall. The k_i in the expression for a wall.
OFFSET
( default=0.0 ) the offset for the start of the wall. The o_i in the expression for a wall.
EXP
( default=2.0 ) the powers for the walls. The e_i in the expression for a wall.
EPS
( default=1.0 ) the values for s_i in the expression for a wall
Options
NUMERICAL_DERIVATIVES
Generated by Doxygen
( default=off ) calculate the derivatives for these quantities numerically
438
Bias
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
The following input tells plumed to add both a lower and an upper walls on the distance between atoms 3 and 5 and
the distance between atoms 2 and 4. The lower and upper limits are defined at different values. The strength of the
walls is the same for the four cases. It also tells plumed to print the energy of the walls.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
UPPER_WALLS ARG=d1,d2 AT=1.0,1.5 KAPPA=150.0,150.0 EXP=2,2 EPS=1,1 OFFSET=0,0 LABEL=uwall
LOWER_WALLS ARG=d1,d2 AT=0.0,1.0 KAPPA=150.0,150.0 EXP=2,2 EPS=1,1 OFFSET=0,0 LABEL=lwall
PRINT ARG=uwall.bias,lwall.bias
(See also DISTANCE and PRINT).
7.6
MAXENT
This is part of the bias module
Add a linear biasing potential on one or more variables fi (x) satisfying the maximum entropy principle as proposed
in Ref. [34] .
Warning
Notice that syntax is still under revision and might change
The resulting biasing potential is given by:
VBIAS (x, t) = KB T
#arguments
X
fi (x, t)λi (t)
i=1
Lagrangian multipliers λi are updated, every PACE steps, according to the following update rule:
λi = λi +
ki
(fexp,i + ξi λi − fi (x))
1 + τti
Generated by Doxygen
7.6 MAXENT
439
k set the initial value of the learning rate and its units are [observable]−2 ps−1 . This can be set with the keyword
KAPPA. The number of components for any KAPPA vector must be equal to the number of arguments of the action.
Variable ξi (λ) is related to the chosen prior to model experimental errors. If a GAUSSIAN prior is used then:
ξi (λ) = −λi σ 2
where σ is the typical expected error on the observable fi . For a LAPLACE prior:
ξi (λ) = −
λi σ 2
2 2
1 − λ 2σ
The value of ξ(λ, t) is written in output as a component named: argument name followed by the string _error.
Setting σ = 0 is equivalent to enforce a pure Maximum Entropy restraint without any noise modelling. This method
can be also used to enforce inequality restraint as shown in following examples.
Notice that a similar method is available as EDS, although with different features and using a different optimization
algorithm.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
force2
the instantaneous value of the squared force due to this bias potential
work
the instantaneous value of the work done by the biasing force
_work
the instantaneous value of the work done by the biasing force for each argument. These quantities
will named with the arguments of the bias followed by the character string _work.
_error
Instantaneous values of the discrepancy between the observable and the restraint center
_coupling
Instantaneous values of Lagrangian multipliers. They are also written by default in a separate
output file.
Compulsory keywords
KAPPA
( default=0.0 ) specifies the initial value for the learning rate
TAU
Specify the dumping time for the learning rate.
TYPE
specify the restraint type. EQUAL to restrain the variable at a given equilibrium value INEQUAL< to
restrain the variable to be smaller than a given value INEQUAL> to restrain the variable to be greater
than a given value
AT
the position of the restraint
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
REWEIGHT
( default=off ) to be used with plumed driver in order to reweight a trajectory a
posteriori
Generated by Doxygen
440
Bias
NO_BROADCAST
( default=off ) If active will avoid Lagrangian multipliers to be communicated to
other replicas.
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
ERROR_TYPE
specify the prior on the error to use.GAUSSIAN: use a Gaussian prior LAPL←ACE: use a Laplace prior
TSTART
time from where to start averaging the Lagrangian multiplier. By default no
average is computed, hence lambda is updated every PACE steps
TEND
time in ps where to stop to compute the average of Lagrangian multiplier. From
this time until the end of the simulation Lagrangian multipliers are kept fix to the
average computed between TSTART and TEND;
ALPHA
default=1.0; To be used with LAPLACE KEYWORD, allows to choose a prior
function proportional to a Gaussian times an exponential function. ALPHA=1
correspond to the LAPLACE prior.
SIGMA
The typical errors expected on observable
FILE
Lagrangian multipliers output file. The default name is: label name followed by
the string .LAGMULT
LEARN_REPLICA
In a multiple replica environment specify which is the reference replica. By
default replica 0 will be used.
APPLY_WEIGHTS
Vector of weights containing 1 in correspondence of each replica that will receive the Lagrangian multiplier from the current one.
PACE
the frequency for Lagrangian multipliers update
PRINT_STRIDE
stride of Lagrangian multipliers output file. If no STRIDE is passed they are
written every time they are updated (PACE).
FMT
specify format for Lagrangian multipliers files (useful to decrease the number
of digits in regtests)
TEMP
the system temperature. This is required if you are reweighting.
RESTART
allows per-action setting of restart (YES/NO/AUTO)
Examples
The following input tells plumed to restrain the distance between atoms 7 and 15 and the distance between atoms
2 and 19, at different equilibrium values, and to print the energy of the restraint. Lagrangian multiplier will be printed
on a file called restraint.LAGMULT with a stride set by the variable PACE to 200ps. Moreover plumed will compute
the average of each Lagrangian multiplier in the window [TSTART,TEND] and use that to continue the simulations
with fixed Lagrangian multipliers.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=7,15 LABEL=d1
Generated by Doxygen
7.7 METAD
441
DISTANCE ATOMS=2,19 LABEL=d2
MAXENT ...
ARG=d1,d2
TYPE=EQUAL
AT=0.2,0.5
KAPPA=35000.0,35000.0
TAU=0.02,0.02
PACE=200
TSTART=100
TEND=500
LABEL=restraint
PRINT ARG=restraint.bias
... MAXENT
Lagrangian multipliers will be printed on a file called restraint.bias The following input tells plumed to restrain the
distance between atoms 7 and 15 to be greater than 0.2 and to print the energy of the restraint
BEGIN_PLUMED_FILE
DISTANCE ATOMS=7,15 LABEL=d
MAXENT ARG=d TYPE=INEQUAL> AT=0.02 KAPPA=35000.0 TAU= LABEL=restraint
PRINT ARG=restraint.bias
(See also DISTANCE and PRINT).
7.7
METAD
This is part of the bias module
Used to performed metadynamics on one or more collective variables.
In a metadynamics simulations a history dependent bias composed of intermittently added Gaussian functions is
added to the potential [45].
V (~s, t) =
X
kτ boundary, the history dependent potential is still updated according to the above equations but the metadynamics force is set to zero for s < boundary. Notice that Gaussian kernels are added also if s < boundary, as
the tails of these Gaussian kernels influence VG in the relevant region s > boundary. In this way, the force on the
system in the region s > boundary comes from both metadynamics and the force field, in the region s < boundary
only from the latter. This approach allows obtaining a history-dependent bias potential VG that fluctuates around a
stable estimator, equal to the negative of the free energy far enough from the boundaries. Note that:
• It works only for one-dimensional biases;
• It works both with and without GRID;
• The interval limit boundary in a region where the free energy derivative is not large;
• If in the region outside the limit boundary the system has a free energy minimum, the INTERVAL keyword
should be used together with a UPPER_WALLS or LOWER_WALLS at boundary.
As a final note, since version 2.0.2 when the system is outside of the selected interval the force is set to zero and
the bias value to the value at the corresponding boundary. This allows acceptances for replica exchange methods
to be computed correctly.
Multiple walkers [50] can also be used. See below the examples.
The c(t) reweighting factor can also be calculated on the fly using the equations presented in [3]. The expression
used to calculate c(t) follows directly from Eq. 3 in [3], where F (~
s) = −γ/(γ −1)V (~s). This gives smoother results
than equivalent Eqs. 13 and Eqs. 14 in that paper. The c(t) is given by the rct component while the bias normalized
by c(t) is given by the rbias component (rbias=bias-rct) which can be used to obtain a reweighted histogram. The
calculation of c(t) is enabled by using the keyword CALC_RCT. By default c(t) is updated every time the bias
changes, but if this slows down the simulation the keyword RCT_USTRIDE can be set to a value higher than 1. This
option requires that a grid is used.
Additional material and examples can be also found in the tutorials:
Generated by Doxygen
7.7 METAD
443
• Belfast tutorial: Metadynamics
• Belfast tutorial: Replica exchange I
• Belfast tutorial: Replica exchange II and Multiple walkers
Notice that at variance with PLUMED 1.3 it is now straightforward to apply concurrent metadynamics as done e.g.
in Ref. [51] . This indeed can be obtained by using the METAD action multiple times in the same input file.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
work
accumulator for work
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
rbias
CALC_RCT
the instantaneous value of the bias normalized using the c(t)
reweighting factor [rbias=bias-rct].This component can be used to
obtain a reweighted histogram.
rct
CALC_RCT
the reweighting factor c(t).
acc
ACCELERATION
the metadynamics acceleration factor
maxbias
CALC_MAX_BIAS
the maximum of the metadynamics V(s, t)
transbias
CALC_TRANSITION_BIAS
the metadynamics transition bias V∗(t)
pace
FREQUENCY_ADAPTIVE
the hill addition frequency when employing frequency adaptive
metadynamics
Compulsory keywords
SIGMA
PACE
the widths of the Gaussian hills
the frequency for hill addition
FILE
( default=HILLS ) a file in which the list of added hills is stored
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
CALC_RCT
( default=off ) calculate the c(t) reweighting factor and use that to obtain the
normalized bias [rbias=bias-rct].This method is not compatible with metadynamics not on a grid.
GRID_SPARSE
( default=off ) use a sparse grid to store hills
GRID_NOSPLINE
( default=off ) don't use spline interpolation with grids
Generated by Doxygen
444
Bias
STORE_GRIDS
( default=off ) store all the grid files the calculation generates. They will be
deleted if this keyword is not present
WALKERS_MPI
( default=off ) Switch on MPI version of multiple walkers - not compatible with
WALKERS_∗ options other than WALKERS_DIR
FLYING_GAUSSIAN
( default=off ) Switch on flying Gaussian method, must be used with WALKE←RS_MPI
( default=off ) Set to TRUE if you want to compute the metadynamics acceleration factor.
( default=off ) Set to TRUE if you want to compute the maximum of the metadynamics V(s, t)
ACCELERATION
CALC_MAX_BIAS
CALC_TRANSITION_BIAS
( default=off ) Set to TRUE if you want to compute a metadynamics transition
bias V∗(t)
FREQUENCY_ADAPTIVE
( default=off ) Set to TRUE if you want to enable frequency adaptive metadynamics such that the frequency for hill addition to change dynamically based
on the acceleration factor.
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
HEIGHT
the heights of the Gaussian hills. Compulsory unless TAU and either BIASF←ACTOR or DAMPFACTOR are given
FMT
specify format for HILLS files (useful for decrease the number of digits in
regtests)
BIASFACTOR
use well tempered metadynamics and use this bias factor. Please note you
must also specify temp
RECT
list of bias factors for all the replicas
DAMPFACTOR
damp hills with exp(-max(V)/( kB T∗DAMPFACTOR)
TTBIASFACTOR
use transition tempered metadynamics with this bias factor. Please note you
must also specify temp
TTBIASTHRESHOLD
use transition tempered metadynamics with this bias threshold. Please note
you must also specify TTBIASFACTOR
TTALPHA
use transition tempered metadynamics with this hill size decay exponent parameter. Please note you must also specify TTBIASFACTOR
TARGET
target to a predefined distribution
TEMP
the system temperature - this is only needed if you are doing well-tempered
metadynamics
TAU
in well tempered metadynamics, sets height to ( kB ∆T ∗pace∗timestep)/tau
GRID_MIN
the lower bounds for the grid
GRID_MAX
the upper bounds for the grid
GRID_BIN
the number of bins for the grid
GRID_SPACING
the approximate grid spacing (to be used as an alternative or together with
GRID_BIN)
Generated by Doxygen
7.7 METAD
445
RCT_USTRIDE
the update stride for calculating the c(t) reweighting factor.The default 1, so
c(t) is updated every time the bias is updated.
GRID_WSTRIDE
write the grid to a file every N steps
GRID_WFILE
the file on which to write the grid
GRID_RFILE
a grid file from which the bias should be read at the initial step of the simulation
ADAPTIVE
use a geometric (=GEOM) or diffusion (=DIFF) based hills width scheme.
Sigma is one number that has distance units or time step dimensions
WALKERS_ID
WALKERS_N
WALKERS_DIR
walker id
number of walkers
shared directory with the hills files from all the walkers
WALKERS_RSTRIDE
stride for reading hills files
INTERVAL
one dimensional lower and upper limits, outside the limits the system will not
feel the biasing force.
SIGMA_MAX
the upper bounds for the sigmas (in CV units) when using adaptive hills. Negative number means no bounds
the lower bounds for the sigmas (in CV units) when using adaptive hills. Negative number means no bounds
a data file from which the acceleration should be read at the initial step of the
simulation
This keyword appears multiple times as TRANSITIONWELL followed by an
integer. Each specifies the coordinates for one well as in transition-tempered
metadynamics. At least one must be provided. You can use multiple instances
of this keyword i.e. TRANSITIONWELL1, TRANSITIONWELL2, TRANSITIO←NWELL3...
the frequency for updating the hill addition pace in frequency adaptive metadynamics, by default this is equal to the value given in PACE
SIGMA_MIN
ACCELERATION_RFILE
TRANSITIONWELL
FA_UPDATE_FREQUENCY
FA_MAX_PACE
the maximum hill addition frequency allowed in frequency adaptive metadynamics. By default there is no maximum value.
FA_MIN_ACCELERATION
only update the hill addition pace in frequency adaptive metadynamics after
reaching the minimum acceleration factor given here. By default it is 1.0.
RESTART
allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM
Only update this action from this time
UPDATE_UNTIL
Only update this action until this time
Examples
The following input is for a standard metadynamics calculation using as collective variables the distance between
atoms 3 and 5 and the distance between atoms 2 and 4. The value of the CVs and the metadynamics bias potential
are written to the COLVAR file every 100 steps.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
METAD ARG=d1,d2 SIGMA=0.2,0.2 HEIGHT=0.3 PACE=500 LABEL=restraint
PRINT ARG=d1,d2,restraint.bias STRIDE=100 FILE=COLVAR
(See also DISTANCE PRINT).
If you use adaptive Gaussian kernels, with diffusion scheme where you use a Gaussian that should cover the
space of 20 time steps in collective variables. Note that in this case the histogram correction is needed when
summing up hills.
Generated by Doxygen
446
Bias
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
METAD ARG=d1,d2 SIGMA=20 HEIGHT=0.3 PACE=500 LABEL=restraint ADAPTIVE=DIFF
PRINT ARG=d1,d2,restraint.bias STRIDE=100 FILE=COLVAR
If you use adaptive Gaussian kernels, with geometrical scheme where you use a Gaussian that should cover
the space of 0.05 nm in Cartesian space. Note that in this case the histogram correction is needed when
summing up hills.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
METAD ARG=d1,d2 SIGMA=0.05 HEIGHT=0.3 PACE=500 LABEL=restraint ADAPTIVE=GEOM
PRINT ARG=d1,d2,restraint.bias STRIDE=100 FILE=COLVAR
When using adaptive Gaussian kernels you might want to limit how the hills width can change. You can use
SIGMA_MIN and SIGMA_MAX keywords. The sigmas should specified in terms of CV so you should use the
CV units. Note that if you use a negative number, this means that the limit is not set. Note also that in this case
the histogram correction is needed when summing up hills.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
METAD ...
ARG=d1,d2 SIGMA=0.05 HEIGHT=0.3 PACE=500 LABEL=restraint ADAPTIVE=GEOM
SIGMA_MIN=0.2,0.1 SIGMA_MAX=0.5,1.0
... METAD
PRINT ARG=d1,d2,restraint.bias STRIDE=100 FILE=COLVAR
Multiple walkers can be also use as in [50] These are enabled by setting the number of walker used, the id of
the current walker which interprets the input file, the directory where the hills containing files resides, and the
frequency to read the other walkers. Here is an example
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
METAD ...
ARG=d1 SIGMA=0.05 HEIGHT=0.3 PACE=500 LABEL=restraint
WALKERS_N=10
WALKERS_ID=3
WALKERS_DIR=../
WALKERS_RSTRIDE=100
... METAD
where WALKERS_N is the total number of walkers, WALKERS_ID is the id of the present walker (starting from
0 ) and the WALKERS_DIR is the directory where all the walkers are located. WALKERS_RSTRIDE is the
number of step between one update and the other. Since version 2.2.5, hills files are automatically flushed
every WALKERS_RSTRIDE steps.
The c(t) reweighting factor can be calculated on the fly using the equations presented in [3] as described above.
This is enabled by using the keyword CALC_RCT, and can be done only if the bias is defined on a grid.
BEGIN_PLUMED_FILE
METAD ...
LABEL=metad
ARG=phi,psi SIGMA=0.20,0.20 HEIGHT=1.20 BIASFACTOR=5 TEMP=300.0 PACE=500
GRID_MIN=-pi,-pi GRID_MAX=pi,pi GRID_BIN=150,150
CALC_RCT
RCT_USTRIDE=10
... METAD
Here we have asked that the calculation is performed every 10 hills deposition by using RCT_USTRIDE keyword. If this keyword is not given, the calculation will by default be performed every time the bias changes. The
c(t) reweighting factor will be given in the rct component while the instantaneous value of the bias potential
normalized using the c(t) reweighting factor is given in the rbias component [rbias=bias-rct] which can be used
to obtain a reweighted histogram or free energy surface using the HISTOGRAM analysis.
Generated by Doxygen
7.7 METAD
447
The kinetics of the transitions between basins can also be analyzed on the fly as in [52]. The flag ACCELER←ATION turn on accumulation of the acceleration factor that can then be used to determine the rate. This method
can be used together with COMMITTOR analysis to stop the simulation when the system get to the target basin.
It must be used together with Well-Tempered Metadynamics. If restarting from a previous metadynamics you
need to use the ACCELERATION_RFILE keyword to give the name of the data file from which the previous
value of the acceleration factor should be read, otherwise the calculation of the acceleration factor will be wrong.
By using the flag FREQUENCY_ADAPTIVE the frequency adaptive scheme introduced in [53] is turned on.
The frequency for hill addition then changes dynamically based on the acceleration factor according to the
following equation
τdep (t) = min τ0 · max
α(t)
, 1 , τc
θ
where τ0 is the initial hill addition frequency given by the PACE keyword, τc is the maximum allowed frequency
given by the FA_MAX_PACE keyword, α(t) is the instantaneous acceleration factor at time t, and θ is a threshold value that acceleration factor has to reach before triggering a change in the hill addition frequency given
by the FA_MIN_ACCELERATION keyword. The frequency for updating the hill addition frequency according to
this equation is given by the FA_UPDATE_FREQUENCY keyword, by default it is the same as the value given
in PACE. The hill hill addition frequency increase monotonously such that if the instantaneous acceleration factor is lower than in the previous updating step the previous τdep is kept rather than updating it to a lower value.
The instantaneous hill addition frequency τdep (t) is outputted to pace component. Note that if restarting from a
previous metadynamics run you need to use the ACCELERATION_RFILE keyword to read in the acceleration
factors from the previous run, otherwise the hill addition frequency will start from the initial frequency.
You can also provide a target distribution using the keyword TARGET [54] [55] [56] The TARGET should be a
grid containing a free-energy (i.e. the - kB T∗log of the desired target distribution). Gaussian kernels will then
be scaled by a factor
eβ(F̃ (s)−F̃max )
Here F̃ (s) is the free energy defined on the grid and F̃max its maximum value. Notice that we here used the
maximum value as in ref [56] This choice allows to avoid exceedingly large Gaussian kernels to be added.
However, it could make the Gaussian too small. You should always choose carefully the HEIGHT parameter
in this case. The grid file should be similar to other PLUMED grid files in that it should contain both the target
free-energy and its derivatives.
Notice that if you wish your simulation to converge to the target free energy you should use the DAMPFACTOR
command to provide a global tempering [57] Alternatively, if you use a BIASFACTOR your simulation will converge
to a free energy that is a linear combination of the target free energy and of the intrinsic free energy determined by
the original force field.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
METAD ...
LABEL=t1
ARG=d1 SIGMA=0.05 TAU=200 DAMPFACTOR=100 PACE=250
GRID_MIN=0 GRID_MAX=2 GRID_BIN=200
TARGET=dist.dat
... METAD
PRINT ARG=d1,t1.bias STRIDE=100 FILE=COLVAR
The header in the file dist.dat for this calculation would read:
#!
#!
#!
#!
#!
FIELDS d1 t1.target der_d1
SET min_d1 0
SET max_d1 2
SET nbins_d1 200
SET periodic_d1 false
Generated by Doxygen
448
Bias
Notice that BIASFACTOR can also be chosen as equal to 1. In this case one will perform unbiased sampling.
Instead of using HEIGHT, one should provide the TAU parameter.
BEGIN_PLUMED_FILE
d: DISTANCE ATOMS=3,5
METAD ARG=d SIGMA=0.1 TAU=4.0 TEMP=300 PACE=100 BIASFACTOR=1.0
The HILLS file obtained will still work with plumed sum_hills so as to plot a free-energy. The case where this
makes sense is probably that of RECT simulations.
Regarding RECT simulations, you can also use the RECT keyword so as to avoid using multiple input files. For
instance, a single input file will be
BEGIN_PLUMED_FILE
d: DISTANCE ATOMS=3,5
METAD ARG=d SIGMA=0.1 TAU=4.0 TEMP=300 PACE=100 RECT=1.0,1.5,2.0,3.0
The number of elements in the RECT array should be equal to the number of replicas.
7.8
MOVINGRESTRAINT
This is part of the bias module
Add a time-dependent, harmonic restraint on one or more variables.
This form of bias can be used to performed steered MD [58] and Jarzynski sampling [59].
The harmonic restraint on your system is given by:
V (~s, t) =
1
κ(t)(~s − ~s0 (t))2
2
The time dependence of κ and ~
s0 are specified by a list of STEP, KAPPA and AT keywords. These keywords tell
plumed what values κ and ~
s0 should have at the time specified by the corresponding STEP keyword. In between
these times the values of κ and ~
s0 are linearly interpolated.
Additional material and examples can be also found in the tutorial Belfast tutorial: Out of equilibrium dynamics
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Generated by Doxygen
7.8 MOVINGRESTRAINT
449
Quantity
Description
bias
the instantaneous value of the bias potential
work
the total work performed changing this restraint
force2
the instantaneous value of the squared force due to this bias potential
_cntr
one or multiple instances of this quantity can be referenced elsewhere in the input file. these quantities will named with the arguments of the bias followed by the character string _cntr. These quantities
give the instantaneous position of the center of the harmonic potential.
_work
one or multiple instances of this quantity can be referenced elsewhere in the input file. These
quantities will named with the arguments of the bias followed by the character string _work. These
quantities tell the user how much work has been done by the potential in dragging the system along
the various colvar axis.
one or multiple instances of this quantity can be referenced elsewhere in the input file. These
quantities will named with the arguments of the bias followed by the character string _kappa. These
quantities tell the user the time dependent value of kappa.
_kappa
Compulsory keywords
VERSE
( default=B ) Tells plumed whether the restraint is only acting for CV larger (U) or smaller (L) than the
restraint or whether it is acting on both sides (B)
STEP
This keyword appears multiple times as STEP x with x=0,1,2,...,n. Each value given represents the
MD step at which the restraint parameters take the values KAPPA x and AT x. You can use multiple
instances of this keyword i.e. STEP1, STEP2, STEP3...
AT
AT x is equal to the position of the restraint at time STEP x. For intermediate times this parameter is
linearly interpolated. If no AT x is specified for STEP x then the values of AT are kept constant during
the interval of time between STEP x − 1 and STEP x. You can use multiple instances of this keyword
i.e. AT1, AT2, AT3...
KAPPA
KAPPA x is equal to the value of the force constants at time STEP x. For intermediate times this
parameter is linearly interpolated. If no KAPPA x is specified for STEP x then the values of KAPPA x
are kept constant during the interval of time between STEP x − 1 and STEP x. You can use multiple
instances of this keyword i.e. KAPPA1, KAPPA2, KAPPA3...
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Generated by Doxygen
450
Bias
Examples
The following input is dragging the distance between atoms 2 and 4 from 1 to 2 in the first 1000 steps, then back in
the next 1000 steps. In the following 500 steps the restraint is progressively switched off.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=2,4 LABEL=d
MOVINGRESTRAINT ...
ARG=d
STEP0=0
AT0=1.0 KAPPA0=100.0
STEP1=1000 AT1=2.0
STEP2=2000 AT2=1.0
STEP3=2500
KAPPA3=0.0
... MOVINGRESTRAINT
The following input is progressively building restraints distances between atoms 1 and 5 and between atoms 2 and
4 in the first 1000 steps. Afterwards, the restraint is kept static.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=1,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
MOVINGRESTRAINT ...
ARG=d1,d2
STEP0=0
AT0=1.0,1.5 KAPPA0=0.0,0.0
STEP1=1000 AT1=1.0,1.5 KAPPA1=1.0,1.0
... MOVINGRESTRAINT
The following input is progressively bringing atoms 1 and 2 close to each other with an upper wall
BEGIN_PLUMED_FILE
DISTANCE ATOMS=1,2 LABEL=d1
MOVINGRESTRAINT ...
ARG=d1
VERSE=U
STEP0=0
AT0=1.0 KAPPA0=10.0
STEP1=1000 AT1=0.0
... MOVINGRESTRAINT
By default the Action is issuing some values which are the work on each degree of freedom, the center of the
harmonic potential, the total bias deposited
(See also DISTANCE).
Attention
Work is not computed properly when KAPPA is time dependent.
7.9
PBMETAD
This is part of the bias module
Used to performed Parallel Bias metadynamics.
This action activate Parallel Bias Metadynamics (PBMetaD) [60], a version of metadynamics [45] in which multiple
Generated by Doxygen
7.9 PBMETAD
451
low-dimensional bias potentials are applied in parallel. In the current implementation, these have the form of monodimensional metadynamics bias potentials:
V (s1 , t), ..., V (sN , t)
where:
(0)
X
V (si , t) =
kτ boundary, the history dependent potential is still updated according to the above equations but the metadynamics force is set to zero for s < boundary. Notice that Gaussians are added also if s < boundary, as the tails of
these Gaussians influence VG in the relevant region s > boundary. In this way, the force on the system in the region
s > boundary comes from both metadynamics and the force field, in the region s < boundary only from the latter.
This approach allows obtaining a history-dependent bias potential VG that fluctuates around a stable estimator,
equal to the negative of the free energy far enough from the boundaries. Note that:
Generated by Doxygen
452
Bias
• It works only for one-dimensional biases;
• It works both with and without GRID;
• The interval limit boundary in a region where the free energy derivative is not large;
• If in the region outside the limit boundary the system has a free energy minimum, the INTERVAL keyword
should be used together with a UPPER_WALLS or LOWER_WALLS at boundary.
Multiple walkers [50] can also be used. See below the examples.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
Compulsory keywords
SIGMA
PACE
the widths of the Gaussian hills
the frequency for hill addition, one for all biases
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
GRID_SPARSE
( default=off ) use a sparse grid to store hills
GRID_NOSPLINE
( default=off ) don't use spline interpolation with grids
WALKERS_MPI
( default=off ) Switch on MPI version of multiple walkers - not compatible with
WALKERS_∗ options other than WALKERS_DIR
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
FILE
files in which the lists of added hills are stored, default names are assigned
using arguments if FILE is not found
Generated by Doxygen
7.9 PBMETAD
453
HEIGHT
the height of the Gaussian hills, one for all biases. Compulsory unless TAU,
TEMP and BIASFACTOR are given
FMT
specify format for HILLS files (useful for decrease the number of digits in
regtests)
BIASFACTOR
use well tempered metadynamics with this bias factor, one for all biases. Please
note you must also specify temp
TEMP
the system temperature - this is only needed if you are doing well-tempered
metadynamics
TAU
in well tempered metadynamics, sets height to ( kB ∆T ∗pace∗timestep)/tau
GRID_RFILES
read grid for the bias
GRID_WSTRIDE
frequency for dumping the grid
GRID_WFILES
GRID_MIN
dump grid for the bias, default names are used if GRID_WSTRIDE is used
without GRID_WFILES.
the lower bounds for the grid
GRID_MAX
the upper bounds for the grid
GRID_BIN
the number of bins for the grid
GRID_SPACING
the approximate grid spacing (to be used as an alternative or together with
GRID_BIN)
SELECTOR
add forces and do update based on the value of SELECTOR
SELECTOR_ID
WALKERS_ID
WALKERS_N
WALKERS_DIR
value of SELECTOR
walker id
number of walkers
shared directory with the hills files from all the walkers
WALKERS_RSTRIDE
stride for reading hills files
INTERVAL_MIN
one dimensional lower limits, outside the limits the system will not feel the biasing force.
INTERVAL_MAX
one dimensional upper limits, outside the limits the system will not feel the
biasing force.
ADAPTIVE
use a geometric (=GEOM) or diffusion (=DIFF) based hills width scheme.
Sigma is one number that has distance units or timestep dimensions
SIGMA_MAX
RESTART
the upper bounds for the sigmas (in CV units) when using adaptive hills. Negative number means no bounds
the lower bounds for the sigmas (in CV units) when using adaptive hills. Negative number means no bounds
allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM
Only update this action from this time
UPDATE_UNTIL
Only update this action until this time
SIGMA_MIN
Examples
The following input is for PBMetaD calculation using as collective variables the distance between atoms 3 and 5
and the distance between atoms 2 and 4. The value of the CVs and the PBMetaD bias potential are written to the
COLVAR file every 100 steps.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
PBMETAD ARG=d1,d2 SIGMA=0.2,0.2 HEIGHT=0.3 PACE=500 LABEL=pb FILE=HILLS_d1,HILLS_d2
PRINT ARG=d1,d2,pb.bias STRIDE=100 FILE=COLVAR
(See also DISTANCE and PRINT).
Generated by Doxygen
454
Bias
If you use well-tempered metadynamics, you should specify a single bias factor and initial Gaussian height.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
PBMETAD ...
ARG=d1,d2 SIGMA=0.2,0.2 HEIGHT=0.3
PACE=500 BIASFACTOR=8 LABEL=pb
FILE=HILLS_d1,HILLS_d2
... PBMETAD
PRINT ARG=d1,d2,pb.bias STRIDE=100 FILE=COLVAR
The following input enables the MPI version of multiple-walkers.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
PBMETAD ...
ARG=d1,d2 SIGMA=0.2,0.2 HEIGHT=0.3
PACE=500 BIASFACTOR=8 LABEL=pb
FILE=HILLS_d1,HILLS_d2
WALKERS_MPI
... PBMETAD
PRINT ARG=d1,d2,pb.bias STRIDE=100 FILE=COLVAR
The disk version of multiple-walkers can be enabled by setting the number of walker used, the id of the current
walker which interprets the input file, the directory where the hills containing files resides, and the frequency to
read the other walkers. Here is an example
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
PBMETAD ...
ARG=d1,d2 SIGMA=0.2,0.2 HEIGHT=0.3
PACE=500 BIASFACTOR=8 LABEL=pb
FILE=HILLS_d1,HILLS_d2
WALKERS_N=10
WALKERS_ID=3
WALKERS_DIR=../
WALKERS_RSTRIDE=100
... PBMETAD
PRINT ARG=d1,d2,pb.bias STRIDE=100 FILE=COLVAR
where WALKERS_N is the total number of walkers, WALKERS_ID is the id of the present walker (starting from
0 ) and the WALKERS_DIR is the directory where all the walkers are located. WALKERS_RSTRIDE is the
number of step between one update and the other.
7.10
RESTRAINT
This is part of the bias module
Adds harmonic and/or linear restraints on one or more variables.
Either or both of SLOPE and KAPPA must be present to specify the linear and harmonic force constants respectively.
The resulting potential is given by:
X ki
i
2
(xi − ai )2 + mi ∗ (xi − ai )
.
Generated by Doxygen
7.10 RESTRAINT
455
The number of components for any vector of force constants must be equal to the number of arguments to the
action.
Additional material and examples can be also found in the tutorial Belfast tutorial: Umbrella sampling
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
force2
the instantaneous value of the squared force due to this bias potential
Compulsory keywords
SLOPE
KAPPA
AT
( default=0.0 ) specifies that the restraint is linear and what the values of the force constants on each
of the variables are
( default=0.0 ) specifies that the restraint is harmonic and what the values of the force constants on
each of the variables are
the position of the restraint
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
The following input tells plumed to restrain the distance between atoms 3 and 5 and the distance between atoms 2
and 4, at different equilibrium values, and to print the energy of the restraint
Generated by Doxygen
456
Bias
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
RESTRAINT ARG=d1,d2 AT=1.0,1.5 KAPPA=150.0,150.0 LABEL=restraint
PRINT ARG=restraint.bias
7.11
UPPER_WALLS
This is part of the bias module
Defines a wall for the value of one or more collective variables, which limits the region of the phase space accessible
during the simulation.
The restraining potential starts acting on the system when the value of the CV is greater (in the case of UPPER←_WALLS) or lower (in the case of LOWER_WALLS) than a certain limit ai (AT) minus an offset oi (OFFSET). The
expression for the bias due to the wall is given by:
P
i
ki ((xi − ai + oi )/si )ei
ki (KAPPA) is an energy constant in internal unit of the code, si (EPS) a rescaling factor and ei (EXP) the exponent
determining the power law. By default: EXP = 2, EPS = 1.0, OFFSET = 0.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
force2
the instantaneous value of the squared force due to this bias potential
Compulsory keywords
AT
the positions of the wall. The a_i in the expression for a wall.
KAPPA
the force constant for the wall. The k_i in the expression for a wall.
OFFSET
( default=0.0 ) the offset for the start of the wall. The o_i in the expression for a wall.
EXP
( default=2.0 ) the powers for the walls. The e_i in the expression for a wall.
EPS
( default=1.0 ) the values for s_i in the expression for a wall
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
Generated by Doxygen
7.12 RESTART
457
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
The following input tells plumed to add both a lower and an upper walls on the distance between atoms 3 and 5 and
the distance between atoms 2 and 4. The lower and upper limits are defined at different values. The strength of the
walls is the same for the four cases. It also tells plumed to print the energy of the walls.
BEGIN_PLUMED_FILE
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 LABEL=d2
UPPER_WALLS ARG=d1,d2 AT=1.0,1.5 KAPPA=150.0,150.0 EXP=2,2 EPS=1,1 OFFSET=0,0 LABEL=uwall
LOWER_WALLS ARG=d1,d2 AT=0.0,1.0 KAPPA=150.0,150.0 EXP=2,2 EPS=1,1 OFFSET=0,0 LABEL=lwall
PRINT ARG=uwall.bias,lwall.bias
7.12
RESTART
This is part of the setup module
Activate restart.
This is a Setup directive and, as such, should appear at the beginning of the input file. It influences the way PLUMED
treat files open for writing (see also Files).
Notice that it is also possible to enable or disable restart on a per-action basis using the RESTART keyword on a
single action. In this case, the keyword should be assigned a value. RESTART=AUTO means that global settings
are used, RESTART=YES or RESTART=NO respectively enable and disable restart for that single action.
Attention
This directive can have also other side effects, e.g. on METAD and PBMETAD and on some analysis action.
Options
NO
( default=off ) switch off restart - can be used to override the behavior of the MD engine
Generated by Doxygen
458
Bias
Examples
Using the following input:
BEGIN_PLUMED_FILE
d: DISTANCE ATOMS=1,2
PRINT ARG=d FILE=out
a new 'out' file will be created. If an old one is on the way, it will be automatically backed up.
On the other hand, using the following input:
BEGIN_PLUMED_FILE
RESTART
d: DISTANCE ATOMS=1,2
PRINT ARG=d FILE=out
the file 'out' will be appended.
In the following case, file out1 will be backed up and file out2 will be concatenated
BEGIN_PLUMED_FILE
RESTART
d1: DISTANCE ATOMS=1,2
d2: DISTANCE ATOMS=1,2
PRINT ARG=d1 FILE=out1 RESTART=NO
PRINT ARG=d2 FILE=out2
In the following case, file out will backed up even if the MD code thinks that we are restarting. Notice that not all
the MD code send to PLUMED information about restarts. If you are not sure, always put RESTART when you are
restarting and nothing when you aren't
BEGIN_PLUMED_FILE
RESTART NO
d1: DISTANCE ATOMS=1,2
PRINT ARG=d1 FILE=out1
Generated by Doxygen
Chapter 8
Additional Modules
Here is collected the documentation for the additional modules contributed to PLUMED.
Module
Description
PLUMED-ISDB
Authors
References
Integrative Structural and
Dynamical Biology with P←LUMED
Logarithmic Mean Force Dynamics
Method for enhanced sampling and for free energy
calculations along collective
variables
MAZE
Method for enhanced sampling and for free energy
calculations along collective
variables
Experiment Directed SimulationMethods for incorporating
additional information about
CVs into MD simulations by
adaptively determined linear
bias parameters
Max Bonomi
Camilloni
Glen Hocky, Andrew White
[26] [65] [66]
Extended-System Adaptive Biasing
Methods
Forcefor performing e←ABF or DRR method to calculate PMF along CVs
Haochuan Chen, Haohao Fu
[36] [67] [68]
Variationally Enhanced Sampling
Module
(VES code)
that implements enhanced sampling methods
based on Variationally Enhanced Sampling
Omar Valsson
[69]
PIV collective variable
To be completed
To be completed
8.1
To be completed
and
Carlo
[61]
Tetsuya Morishita,
Watanabe
Naoki
[62] [63] [64]
Tetsuya Morishita,
Watanabe
Naoki
[62] [63] [64]
PLUMED-ISDB
Here are listed the collective variables, functions and biases originally developed for the Integrative Structural and
Dynamical Biology module of PLUMED. They are related but not limited to the interpretation and modelling of
experimental data in molecular modelling.
• CVs Documentation
460
Additional Modules
• Functions Documentation
• Biases Documentation
Furthermore using SELECTOR it is possible to define a variable inside the PLUMED code that can be used and
modified by other actions. For example, a SELECTOR can be used in combination with RESCALE to activate a
simulated-tempering like approach.
Additional tutorials focused on the ISDB module are included in the following and are meant as advanced tutorials.
• Tutorials
8.1.1
CVs Documentation
The following list contains descriptions of a number of the colvars that are currently implemented in the PLU←MED-ISDB module. These collective variables are related to the definitions of models to interpret experimental
observables. They can be used in combination with any other collective variable, function or bias also outside the
ISDB module.
CS2BACKBONE
Calculates the backbone chemical shifts for a protein.
EMMI
Calculate the fit of a structure or ensemble of structures with a cryo-EM density map.
FRET
Calculates the FRET efficiency between a pair of atoms.The efficiency is calculated using
the Forster relation:
JCOUPLING
Calculates 3 J coupling constants for a dihedral angle.
NOE
Calculates NOE intensities as sums of 1/r∧ 6, also averaging over multiple equivalent atoms
or ambiguous NOE.
PCS
Calculates the Pseudo-contact shift of a nucleus determined by the presence of a metal ion
susceptible to anisotropic magnetization.
PRE
Calculates the Paramagnetic Resonance Enhancement intensity ratio between a spin label
atom and a list of atoms .
Calculates the (Residual) Dipolar Coupling between two atoms.
RDC
SAXS
8.1.1.1
Calculates SAXS scattered intensity using either the Debye equation or the harmonic sphere
approximation.
CS2BACKBONE
This is part of the isdb module
Calculates the backbone chemical shifts for a protein.
The functional form is that of CamShift [70]. The chemical shift of the selected nuclei can be saved as components.
Alternatively one can calculate either the CAMSHIFT score (useful as a collective variable [71] or as a scoring
function [72]) or a METAINFERENCE score (using DOSCORE). For these two latter cases experimental chemical
shifts must be provided.
CS2BACKBONE calculation can be relatively heavy because it often uses a large number of atoms, it can be run in
parallel using MPI and OpenMP.
As a general rule, when using CS2BACKBONE or other experimental restraints it may be better to increase the
accuracy of the constraint algorithm due to the increased strain on the bonded structure. In the case of GROMACS
it is safer to use lincs-iter=2 and lincs-order=6.
Generated by Doxygen
8.1 PLUMED-ISDB
461
In general the system for which chemical shifts are calculated must be completely included in ATOMS and a T←EMPLATE pdb file for the same atoms should be provided as well in the folder DATADIR. The system is made
automatically whole unless NOPBC is used, in particular if the system is made by multiple chains it is usually
better to use NOPBC and make the molecule whole WHOLEMOLECULES selecting an appropriate order of the
atoms. The pdb file is needed to the generate a simple topology of the protein. For histidine residues in protonation
states different from D the HIE/HSE HIP/HSP name should be used. GLH and ASH can be used for the alternative
protonation of GLU and ASP. Non-standard amino acids and other molecules are not yet supported, but in principle
they can be named UNK. If multiple chains are present the chain identifier must be in the standard PDB format,
together with the TER keyword at the end of each chain. Termini groups like ACE or NME should be removed from
the TEMPLATE pdb because they are not recognized by CS2BACKBONE.
In addition to a pdb file one needs to provide a list of chemical shifts to be calculated using one file per nucleus type
(CAshifts.dat, CBshifts.dat, Cshifts.dat, Hshifts.dat, HAshifts.dat, Nshifts.dat), add only the files for the nuclei you
need, but each file should include all protein residues. A chemical shift for a nucleus is calculated if a value greater
than 0 is provided. For practical purposes the value can correspond to the experimental value. Residues numbers
should match that used in the pdb file, but must be positive, so double check the pdb. The first and last residue of
each chain should be preceded by a # character.
CAshifts.dat:
#1 0.0
2 55.5
3 58.4
.
.
#last 0.0
#first of second chain
.
#last of second chain
The default behavior is to store the values for the active nuclei in components (ca_#, cb_#, co_#, ha_#, hn_#,
nh_# and expca_#, expcb_#, expco_#, expha_#, exphn_#, exp_nh#) with NOEXP it is possible to only store the
back-calculated values, where # includes a chain and residue number.
One additional file is always needed in the folder DATADIR: camshift.db. This file includes all the parameters
needed to calculate the chemical shifts and can be found in regtest/isdb/rt-cs2backbone/data/ .
Additional material and examples can be also found in the tutorial Belfast tutorial: NMR restraints as well as in the
cs2backbone regtests in the isdb folder.
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Generated by Doxygen
Quantity
Description
sigma
uncertainty parameter
sigmaMean
uncertainty in the mean estimate
acceptSigma
MC acceptance
ha
the calculated Ha hydrogen chemical shifts
hn
the calculated H hydrogen chemical shifts
nh
the calculated N nitrogen chemical shifts
ca
cb
co
expha
the calculated Ca carbon chemical shifts
the calculated Cb carbon chemical shifts
the calculated C' carbon chemical shifts
the experimental Ha hydrogen chemical shifts
462
Additional Modules
exphn
the experimental H hydrogen chemical shifts
expnh
the experimental N nitrogen chemical shifts
expca
the experimental Ca carbon chemical shifts
expcb
the experimental Cb carbon chemical shifts
expco
the experimental C' carbon chemical shifts
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
acceptScale
SCALEDATA
MC acceptance
weight
REWEIGHT
weights of the weighted average
biasDer
REWEIGHT
derivatives with respect to the bias
scale
SCALEDATA
scale parameter
offset
ADDOFFSET
offset parameter
ftilde
GENERIC
ensemble average estimator
The atoms involved can be specified using
ATOMS
The atoms to be included in the calculation, e.g. the whole protein.. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
NOISETYPE
( default=MGAUSS ) functional form of the noise (GAUSS,MGAUSS,OUTLIERS,MOUT←LIERS,GENERIC)
LIKELIHOOD
( default=GAUSS ) the likelihood for the GENERIC metainference model, GAUSS or LOGN
DFTILDE
( default=0.1 ) fraction of sigma_mean used to evolve ftilde
SCALE0
( default=1.0 ) initial value of the scaling factor
SCALE_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
OFFSET0
( default=0.0 ) initial value of the offset
OFFSET_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
SIGMA0
( default=1.0 ) initial value of the uncertainty parameter
SIGMA_MIN
( default=0.0 ) minimum value of the uncertainty parameter
SIGMA_MAX
( default=10. ) maximum value of the uncertainty parameter
OPTSIGMAMEAN
( default=NONE ) Set to NONE/SEM to manually set sigma mean, or to estimate it on the
fly
WRITE_STRIDE
DATADIR
( default=10000 ) write the status to a file every N steps, this can be used for
restart/continuation
( default=data/ ) The folder with the experimental chemical shifts.
TEMPLATE
( default=template.pdb ) A PDB file of the protein system to initialize ALMOST.
NEIGH_FREQ
( default=20 ) Period in step for neighbor list update.
Options
Generated by Doxygen
8.1 PLUMED-ISDB
463
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
DOSCORE
( default=off ) activate metainference
NOENSEMBLE
( default=off ) don't perform any replica-averaging
REWEIGHT
( default=off ) simple REWEIGHT using the ARG as energy
SCALEDATA
( default=off ) Set to TRUE if you want to sample a scaling factor common to all
values and replicas
ADDOFFSET
( default=off ) Set to TRUE if you want to sample an offset common to all values
and replicas
NOPBC
SERIAL
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Perform the calculation in serial - for debug purpose
CAMSHIFT
( default=off ) Set to TRUE if you to calculate a single CamShift score.
NOEXP
( default=off ) Set to TRUE if you don't want to have fixed components with the
experimental values.
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
AVERAGING
Stride for calculation of averaged weights and sigma_mean
SCALE_MIN
minimum value of the scaling factor
SCALE_MAX
maximum value of the scaling factor
DSCALE
maximum MC move of the scaling factor
OFFSET_MIN
OFFSET_MAX
DOFFSET
REGRES_ZERO
minimum value of the offset
maximum value of the offset
maximum MC move of the offset
stride for regression with zero offset
DSIGMA
maximum MC move of the uncertainty parameter
SIGMA_MEAN0
starting value for the uncertainty in the mean estimate
TEMP
the system temperature - this is only needed if code doesn't pass the temperature to plumed
MC_STEPS
number of MC steps
MC_STRIDE
MC_CHUNKSIZE
STATUS_FILE
SELECTOR
NSELECT
MC stride
MC chunksize
write a file with all the data useful for restart/continuation of Metainference
name of selector
range of values for selector [0, N-1]
RESTART
allows per-action setting of restart (YES/NO/AUTO)
Examples
Generated by Doxygen
464
Additional Modules
In this first example the chemical shifts are used to calculate a collective variable to be used in NMR driven Metadynamics [71] :
BEGIN_PLUMED_FILE
whole: GROUP ATOMS=2612-2514:-1,961-1:-1,2466-962:-1,2513-2467:-1
WHOLEMOLECULES ENTITY0=whole
cs: CS2BACKBONE ATOMS=1-2612 DATADIR=../data/ TEMPLATE=template.pdb CAMSHIFT NOPBC
metad: METAD ARG=cs HEIGHT=0.5 SIGMA=0.1 PACE=200 BIASFACTOR=10
PRINT ARG=cs,metad.bias FILE=COLVAR STRIDE=100
In this second example the chemical shifts are used as replica-averaged restrained as in [73] [74].
BEGIN_PLUMED_FILE
cs: CS2BACKBONE ATOMS=1-174 DATADIR=data/
encs: ENSEMBLE ARG=(cs\.hn_.*),(cs\.nh_.*)
stcs: STATS ARG=encs.* SQDEVSUM PARARG=(cs\.exphn_.*),(cs\.expnh_.*)
RESTRAINT ARG=stcs.sqdevsum AT=0 KAPPA=0 SLOPE=24
PRINT ARG=(cs\.hn_.*),(cs\.nh_.*) FILE=RESTRAINT STRIDE=100
This third example show how to use chemical shifts to calculate a METAINFERENCE score .
BEGIN_PLUMED_FILE
cs: CS2BACKBONE ATOMS=1-174 DATADIR=data/ DOSCORE
csbias: BIASVALUE ARG=cs.score
PRINT ARG=(cs\.hn_.*),(cs\.nh_.*) FILE=CS.dat STRIDE=1000
PRINT ARG=cs.score FILE=BIAS STRIDE=100
8.1.1.2
EMMI
This is part of the isdb module
Calculate the fit of a structure or ensemble of structures with a cryo-EM density map.
This action implements the multi-scale Bayesian approach to cryo-EM data fitting introduced in Ref. [75] . This
method allows efficient and accurate structural modeling of cryo-electron microscopy density maps at multiple
scales, from coarse-grained to atomistic resolution, by addressing the presence of random and systematic errors in
the data, sample heterogeneity, data correlation, and noise correlation.
The experimental density map is fit by a Gaussian Mixture Model (GMM), which is provided as an external file
specified by the keyword GMM_FILE. We are currently working on a web server to perform this operation. In the
meantime, the user can request a stand-alone version of the GMM code at massimiliano.bonomi_AT_gmail.com.
When run in single-replica mode, this action allows atomistic, flexible refinement of an individual structure into a
density map. Combined with a multi-replica framework (such as the -multi option in GROMACS), the user can
model an ensemble of structures using the Metainference approach [76] .
Warning
To use EMMI, the user should always add a MOLINFO line and specify a pdb file of the system.
Generated by Doxygen
8.1 PLUMED-ISDB
465
Note
To enhance sampling in single-structure refinement, one can use a Replica Exchange Method, such as Parallel
Tempering. In this case, the user should add the NO_AVER flag to the input line.
EMMI can be used in combination with periodic and non-periodic systems. In the latter case, one should add
the NOPBC flag to the input line
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
score
Bayesian score
scoreb
Beta Bayesian score
The atoms involved can be specified using
ATOMS
atoms for which we calculate the density map, typically all heavy atoms. For more information on how
to specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
GMM_FILE
file with the parameters of the GMM components
TEMP
temperature
NL_CUTOFF
The cutoff in overlap for the neighbor list
NL_STRIDE
The frequency with which we are updating the neighbor list
SIGMA_MEAN
starting value for the uncertainty in the mean estimate
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
NO_AVER
( default=off ) don't do ensemble averaging in multi-replica mode
ANALYSIS
( default=off ) run in analysis mode
Examples
In this example, we perform a single-structure refinement based on an experimental cryo-EM map. The map is fit
with a GMM, whose parameters are listed in the file GMM_fit.dat. This file contains one line per GMM component
in the following format:
Generated by Doxygen
466
Additional Modules
#! FIELDS Id Weight Mean_0 Mean_1 Mean_2 Cov_00 Cov_01 Cov_02 Cov_11 Cov_12 Cov_22 Beta
0 2.9993805e+01
6.54628 10.37820 -0.92988 2.078920e-02 1.216254e-03 5.990827e-04 2.556246e-02 8.41183
1 2.3468312e+01
6.56095 10.34790 -0.87808 1.879859e-02 6.636049e-03 3.682865e-04 3.194490e-02 1.75052
...
To accelerate the computation of the Bayesian score, one can:
• use neighbor lists, specified by the keywords NL_CUTOFF and NL_STRIDE;
• calculate the restraint every other step (or more).
All the heavy atoms of the system are used to calculate the density map. This list can conveniently be provided
using a GROMACS index file.
The input file looks as follows:
BEGIN_PLUMED_FILE
# include pdb info
MOLINFO STRUCTURE=prot.pdb
# all heavy atoms
protein-h: GROUP NDX_FILE=index.ndx NDX_GROUP=Protein-H
# create EMMI score
gmm: EMMI NOPBC SIGMA_MEAN=0.01 TEMP=300.0 NL_STRIDE=100 NL_CUTOFF=0.01 GMM_FILE=GMM_fit.dat ATOMS=protein-h
# translate into bias - apply every 2 steps
emr: BIASVALUE ARG=gmm.scoreb STRIDE=2
PRINT ARG=emr.* FILE=COLVAR STRIDE=500 FMT=%20.10f
8.1.1.3
FRET
This is part of the isdb module
Calculates the FRET efficiency between a pair of atoms. The efficiency is calculated using the Forster relation:
E=
1
1 + (R/R0 )6
where R is the distance and R0 is the Forster radius.
By default the distance is computed taking into account periodic boundary conditions. This behavior can be changed
with the NOPBC flag.
The atoms involved can be specified using
ATOMS
the pair of atom that we are calculating the distance between. For more information on how to specify
lists of atoms see Groups and Virtual Atoms
Generated by Doxygen
8.1 PLUMED-ISDB
467
Compulsory keywords
R0
The value of the Forster radius.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
Examples
The following input tells plumed to print the FRET efficiencies calculated as a function of the distance between
atoms 3 and 5 and the distance between atoms 2 and 4.
BEGIN_PLUMED_FILE
fe1: FRET ATOMS=3,5 R0=5.5
fe2: FRET ATOMS=2,4 R0=5.5
PRINT ARG=fe1,fe2
The following input computes the FRET efficiency calculated on the terminal atoms of a polymer of 100 atoms and
keeps it at a value around 0.5.
BEGIN_PLUMED_FILE
WHOLEMOLECULES ENTITY0=1-100
fe: FRET ATOMS=1,100 R0=5.5 NOPBC
RESTRAINT ARG=fe KAPPA=100 AT=0.5
Notice that NOPBC is used to be sure that if the distance is larger than half the simulation box the distance is
compute properly. Also notice that, since many MD codes break molecules across cell boundary, it might be
necessary to use the WHOLEMOLECULES keyword (also notice that it should be before FRET). Just be sure that
the ordered list provide to WHOLEMOLECULES has the following properties:
• Consecutive atoms should be closer than half-cell throughout the entire simulation.
• Atoms required later for the distance (e.g. 1 and 100) should be included in the list
8.1.1.4
JCOUPLING
This is part of the isdb module
Calculates 3 J coupling constants for a dihedral angle.
The J-coupling between two atoms is given by the Karplus relation:
3
Generated by Doxygen
J(θ) = A cos2 (θ + ∆θ) + B cos(θ + ∆θ) + C
468
Additional Modules
where A, B and C are the Karplus parameters and ∆θ is an additional constant added on to the dihedral angle θ .
The Karplus parameters are determined empirically and are dependent on the type of J-coupling.
This collective variable computes the J-couplings for a set of atoms defining a dihedral angle. You can specify the
atoms involved using the MOLINFO notation. You can also specify the experimental couplings using the ADD←COUPLINGS flag and COUPLING keywords. These will be included in the output. You must choose the type of
coupling using the type keyword, you can also supply custom Karplus parameters using TYPE=CUSTOM and the
A, B, C and SHIFT keywords. You will need to make sure you are using the correct dihedral angle:
• Ha-N: ψ
• Ha-HN: φ
• N-C γ : χ1
• CO-C γ : χ1
J-couplings can be used to calculate a Metainference score using the internal keyword DOSCORE and all the
options of METAINFERENCE .
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Quantity
Description
sigma
uncertainty parameter
sigmaMean
uncertainty in the mean estimate
acceptSigma
MC acceptance
j
the calculated J-coupling
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
acceptScale
SCALEDATA
MC acceptance
weight
REWEIGHT
weights of the weighted average
biasDer
REWEIGHT
derivatives with respect to the bias
scale
SCALEDATA
scale parameter
offset
ADDOFFSET
offset parameter
ftilde
GENERIC
ensemble average estimator
exp
ADDCOUPLINGS
the experimental J-coupling
The atoms involved can be specified using
ATOMS
the 4 atoms involved in each of the bonds for which you wish to calculate the J-coupling. Keywords
like ATOMS1, ATOMS2, ATOMS3,... should be listed and one J-coupling will be calculated for each
ATOMS keyword you specify. You can use multiple instances of this keyword i.e. ATOMS1, ATOMS2,
ATOMS3...
Generated by Doxygen
8.1 PLUMED-ISDB
469
Compulsory keywords
NOISETYPE
( default=MGAUSS ) functional form of the noise (GAUSS,MGAUSS,OUTLIERS,MOUT←LIERS,GENERIC)
LIKELIHOOD
( default=GAUSS ) the likelihood for the GENERIC metainference model, GAUSS or LOGN
DFTILDE
( default=0.1 ) fraction of sigma_mean used to evolve ftilde
SCALE0
( default=1.0 ) initial value of the scaling factor
SCALE_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
OFFSET0
( default=0.0 ) initial value of the offset
OFFSET_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
SIGMA0
( default=1.0 ) initial value of the uncertainty parameter
SIGMA_MIN
( default=0.0 ) minimum value of the uncertainty parameter
SIGMA_MAX
( default=10. ) maximum value of the uncertainty parameter
OPTSIGMAMEAN
( default=NONE ) Set to NONE/SEM to manually set sigma mean, or to estimate it on the
fly
WRITE_STRIDE
( default=10000 ) write the status to a file every N steps, this can be used for
restart/continuation
Type of J-coupling to compute (HAN,HAHN,CCG,NCG,CUSTOM)
TYPE
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
DOSCORE
( default=off ) activate metainference
NOENSEMBLE
( default=off ) don't perform any replica-averaging
REWEIGHT
( default=off ) simple REWEIGHT using the ARG as energy
SCALEDATA
( default=off ) Set to TRUE if you want to sample a scaling factor common to all
values and replicas
ADDOFFSET
( default=off ) Set to TRUE if you want to sample an offset common to all values
and replicas
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Set this flag if you want to have fixed components with the experimental values.
ADDCOUPLINGS
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
AVERAGING
Stride for calculation of averaged weights and sigma_mean
Generated by Doxygen
470
Additional Modules
SCALE_MIN
minimum value of the scaling factor
SCALE_MAX
maximum value of the scaling factor
DSCALE
maximum MC move of the scaling factor
OFFSET_MIN
OFFSET_MAX
DOFFSET
REGRES_ZERO
minimum value of the offset
maximum value of the offset
maximum MC move of the offset
stride for regression with zero offset
DSIGMA
maximum MC move of the uncertainty parameter
SIGMA_MEAN0
starting value for the uncertainty in the mean estimate
TEMP
the system temperature - this is only needed if code doesn't pass the temperature to plumed
MC_STEPS
number of MC steps
MC_STRIDE
MC_CHUNKSIZE
STATUS_FILE
SELECTOR
NSELECT
MC stride
MC chunksize
write a file with all the data useful for restart/continuation of Metainference
name of selector
range of values for selector [0, N-1]
RESTART
allows per-action setting of restart (YES/NO/AUTO)
A
Karplus parameter A
B
Karplus parameter B
C
Karplus parameter C
SHIFT
Angle shift in radians
COUPLING
Add an experimental value for each coupling You can use multiple instances of
this keyword i.e. COUPLING1, COUPLING2, COUPLING3...
Examples
In the following example we calculate the Ha-N J-coupling from a set of atoms involved in dihedral ψ angles in the
peptide backbone. We also add the experimental data points and compute the correlation and other measures and
finally print the results.
BEGIN_PLUMED_FILE
MOLINFO MOLTYPE=protein STRUCTURE=peptide.pdb
WHOLEMOLECULES ENTITY0=1-111
JCOUPLING ...
ADDCOUPLINGS
TYPE=HAN
ATOMS1=@psi-2
ATOMS2=@psi-4
ATOMS3=@psi-5
ATOMS4=@psi-7
ATOMS5=@psi-8
LABEL=jhan
... JCOUPLING
COUPLING1=-0.49
COUPLING2=-0.54
COUPLING3=-0.53
COUPLING4=-0.39
COUPLING5=-0.39
jhanst: STATS ARG=(jhan\.j_.*) PARARG=(jhan\.exp_.*)
PRINT ARG=jhanst.*,jhan.* FILE=COLVAR STRIDE=100
8.1.1.5
NOE
Generated by Doxygen
8.1 PLUMED-ISDB
471
This is part of the isdb module
Calculates NOE intensities as sums of 1/r∧ 6, also averaging over multiple equivalent atoms or ambiguous NOE.
Each NOE is defined by two groups containing the same number of atoms, distances are calculated in pairs,
transformed in 1/r∧ 6, summed and saved as components.
Neq
1 X 1
( ))
N OE() = (
Neq j rj6
NOE can be used to calculate a Metainference score over one or more replicas using the intrinsic implementation
of METAINFERENCE that is activated by DOSCORE.
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Quantity
Description
sigma
uncertainty parameter
sigmaMean
uncertainty in the mean estimate
acceptSigma
MC acceptance
noe
the # NOE
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
acceptScale
SCALEDATA
MC acceptance
weight
REWEIGHT
weights of the weighted average
biasDer
REWEIGHT
derivatives with respect to the bias
scale
SCALEDATA
scale parameter
offset
ADDOFFSET
offset parameter
ftilde
GENERIC
ensemble average estimator
exp
ADDEXP
the # NOE experimental distance
The atoms involved can be specified using
GROUPA
GROUPB
the atoms involved in each of the contacts you wish to calculate. Keywords like GROUPA1, GR←OUPA2, GROUPA3,... should be listed and one contact will be calculated for each ATOM keyword
you specify. You can use multiple instances of this keyword i.e. GROUPA1, GROUPA2, GROUP←A3...
the atoms involved in each of the contacts you wish to calculate. Keywords like GROUPB1, GR←OUPB2, GROUPB3,... should be listed and one contact will be calculated for each ATOM keyword
you specify. You can use multiple instances of this keyword i.e. GROUPB1, GROUPB2, GROUP←B3...
Generated by Doxygen
472
Additional Modules
Compulsory keywords
NOISETYPE
( default=MGAUSS ) functional form of the noise (GAUSS,MGAUSS,OUTLIERS,MOUT←LIERS,GENERIC)
LIKELIHOOD
( default=GAUSS ) the likelihood for the GENERIC metainference model, GAUSS or LOGN
DFTILDE
( default=0.1 ) fraction of sigma_mean used to evolve ftilde
SCALE0
( default=1.0 ) initial value of the scaling factor
SCALE_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
OFFSET0
( default=0.0 ) initial value of the offset
OFFSET_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
SIGMA0
( default=1.0 ) initial value of the uncertainty parameter
SIGMA_MIN
( default=0.0 ) minimum value of the uncertainty parameter
SIGMA_MAX
( default=10. ) maximum value of the uncertainty parameter
OPTSIGMAMEAN
( default=NONE ) Set to NONE/SEM to manually set sigma mean, or to estimate it on the
fly
WRITE_STRIDE
( default=10000 ) write the status to a file every N steps, this can be used for
restart/continuation
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
DOSCORE
( default=off ) activate metainference
NOENSEMBLE
( default=off ) don't perform any replica-averaging
REWEIGHT
( default=off ) simple REWEIGHT using the ARG as energy
SCALEDATA
( default=off ) Set to TRUE if you want to sample a scaling factor common to all
values and replicas
ADDOFFSET
( default=off ) Set to TRUE if you want to sample an offset common to all values
and replicas
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Set to TRUE if you want to have fixed components with the experimental reference values.
ADDEXP
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
AVERAGING
Stride for calculation of averaged weights and sigma_mean
SCALE_MIN
minimum value of the scaling factor
Generated by Doxygen
8.1 PLUMED-ISDB
473
SCALE_MAX
maximum value of the scaling factor
DSCALE
maximum MC move of the scaling factor
OFFSET_MIN
OFFSET_MAX
DOFFSET
REGRES_ZERO
minimum value of the offset
maximum value of the offset
maximum MC move of the offset
stride for regression with zero offset
DSIGMA
maximum MC move of the uncertainty parameter
SIGMA_MEAN0
starting value for the uncertainty in the mean estimate
TEMP
the system temperature - this is only needed if code doesn't pass the temperature to plumed
MC_STEPS
number of MC steps
MC_STRIDE
MC_CHUNKSIZE
STATUS_FILE
SELECTOR
NSELECT
MC stride
MC chunksize
write a file with all the data useful for restart/continuation of Metainference
name of selector
range of values for selector [0, N-1]
RESTART
allows per-action setting of restart (YES/NO/AUTO)
NOEDIST
Add an experimental value for each NOE. You can use multiple instances of
this keyword i.e. NOEDIST1, NOEDIST2, NOEDIST3...
Examples
In the following examples three noes are defined, the first is calculated based on the distances of atom 12 and 3-2; the second is defined by the distance 5-7 and the third by the distances 4-15,4-16,8-15,8-16.
METAINFERENCE is activated using DOSCORE.
BEGIN_PLUMED_FILE
NOE ...
GROUPA1=1,3 GROUPB1=2,2
GROUPA2=5 GROUPB2=7
GROUPA3=4,4,8,8 GROUPB3=15,16,15,16
DOSCORE
LABEL=noes
... NOE
PRINT ARG=noes.* FILE=colvar
8.1.1.6
PCS
This is part of the isdb module
Calculates the Pseudo-contact shift of a nucleus determined by the presence of a metal ion susceptible to
anisotropic magnetization.
The PCS of an atomic nucleus depends on the θ angle between the vector from the spin-label to the nucleus
and the external magnetic field and the module of the vector itself [77] . While in principle the averaging resulting
from the tumbling should remove the pseudo-contact shift, in presence of the NMR magnetic field the magnetically
anisotropic molecule bound to system will break the rotational symmetry does resulting in measurable values for
the PCS and RDC.
PCS values can also be calculated using a Single Value Decomposition approach, in this case the code rely on the
a set of function from the GNU Scientific Library (GSL). (With SVD forces are not currently implemented).
Replica-Averaged simulations can be performed using PCS values, ENSEMBLE, STATS and RESTRAINT . Metainference simulations can be performed with this CV and METAINFERENCE .
Generated by Doxygen
474
Additional Modules
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Quantity
Description
sigma
uncertainty parameter
sigmaMean
uncertainty in the mean estimate
acceptSigma
MC acceptance
rdc
the calculated # RDC
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
acceptScale
SCALEDATA
MC acceptance
weight
REWEIGHT
weights of the weighted average
biasDer
REWEIGHT
derivatives with respect to the bias
scale
SCALEDATA
scale parameter
offset
ADDOFFSET
offset parameter
ftilde
GENERIC
ensemble average estimator
exp
SVD/ADDCOUPLINGS
the experimental # RDC
The atoms involved can be specified using
ATOMS
the couple of atoms involved in each of the bonds for which you wish to calculate the RDC. Keywords
like ATOMS1, ATOMS2, ATOMS3,... should be listed and one dipolar coupling will be calculated for
each ATOMS keyword you specify. You can use multiple instances of this keyword i.e. ATOMS1,
ATOMS2, ATOMS3...
Compulsory keywords
NOISETYPE
( default=MGAUSS ) functional form of the noise (GAUSS,MGAUSS,OUTLIERS,MOUT←LIERS,GENERIC)
LIKELIHOOD
( default=GAUSS ) the likelihood for the GENERIC metainference model, GAUSS or LOGN
DFTILDE
( default=0.1 ) fraction of sigma_mean used to evolve ftilde
SCALE0
( default=1.0 ) initial value of the scaling factor
SCALE_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
OFFSET0
( default=0.0 ) initial value of the offset
OFFSET_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
SIGMA0
( default=1.0 ) initial value of the uncertainty parameter
SIGMA_MIN
( default=0.0 ) minimum value of the uncertainty parameter
SIGMA_MAX
( default=10. ) maximum value of the uncertainty parameter
OPTSIGMAMEAN
( default=NONE ) Set to NONE/SEM to manually set sigma mean, or to estimate it on the
fly
Generated by Doxygen
8.1 PLUMED-ISDB
WRITE_STRIDE
475
GYROM
( default=10000 ) write the status to a file every N steps, this can be used for
restart/continuation
( default=1. ) Add the product of the gyromagnetic constants for the bond.
SCALE
( default=1. ) Add the scaling factor to take into account concentration and other effects.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
DOSCORE
( default=off ) activate metainference
NOENSEMBLE
( default=off ) don't perform any replica-averaging
REWEIGHT
( default=off ) simple REWEIGHT using the ARG as energy
SCALEDATA
( default=off ) Set to TRUE if you want to sample a scaling factor common to all
values and replicas
ADDOFFSET
( default=off ) Set to TRUE if you want to sample an offset common to all values
and replicas
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Set to TRUE if you want to back calculate using Single Value
Decomposition (need GSL at compilation time).
SVD
ADDCOUPLINGS
( default=off ) Set to TRUE if you want to have fixed components with the experimental values.
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
AVERAGING
Stride for calculation of averaged weights and sigma_mean
SCALE_MIN
minimum value of the scaling factor
SCALE_MAX
maximum value of the scaling factor
DSCALE
maximum MC move of the scaling factor
OFFSET_MIN
OFFSET_MAX
DOFFSET
REGRES_ZERO
minimum value of the offset
maximum value of the offset
maximum MC move of the offset
stride for regression with zero offset
DSIGMA
maximum MC move of the uncertainty parameter
SIGMA_MEAN0
starting value for the uncertainty in the mean estimate
TEMP
the system temperature - this is only needed if code doesn't pass the temperature to plumed
MC_STEPS
number of MC steps
MC_STRIDE
MC_CHUNKSIZE
MC stride
MC chunksize
Generated by Doxygen
476
Additional Modules
STATUS_FILE
SELECTOR
NSELECT
write a file with all the data useful for restart/continuation of Metainference
name of selector
range of values for selector [0, N-1]
RESTART
allows per-action setting of restart (YES/NO/AUTO)
COUPLING
Add an experimental value for each coupling (needed by SVD and useful for
STATS). You can use multiple instances of this keyword i.e. COUPLING1,
COUPLING2, COUPLING3...
Examples
In the following example five PCS values are defined and their correlation with respect to a set of experimental data
is calculated and restrained. In addition, and only for analysis purposes, the same PCS values are calculated using
a Single Value Decomposition algorithm.
BEGIN_PLUMED_FILE
PCS ...
ATOMS1=20,21
ATOMS2=20,38
ATOMS3=20,57
ATOMS4=20,77
ATOMS5=20,93
LABEL=nh
... PCS
enh: ENSEMBLE ARG=nh.*
st: STATS ARG=enh.* PARAMETERS=8.17,-8.271,-10.489,-9.871,-9.152
pcse: RESTRAINT ARG=st.corr KAPPA=0. SLOPE=-25000.0 AT=1.
PRINT ARG=st.corr,pcse.bias FILE=colvar
8.1.1.7
PRE
This is part of the isdb module
Calculates the Paramagnetic Resonance Enhancement intensity ratio between a spin label atom and a list of atoms
.
The reference atom for the spin label is added with SPINLABEL, the affected atom(s) are give as numbered GR←OUPA1, GROUPA2, ... The additional parameters needed for the calculation are given as INEPT, the inept time,
TAUC the correlation time, OMEGA, the Larmor frequency and RTWO for the relaxation time.
METAINFERENCE can be activated using DOSCORE and the other relevant keywords.
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Generated by Doxygen
8.1 PLUMED-ISDB
477
Quantity
Description
sigma
uncertainty parameter
sigmaMean
uncertainty in the mean estimate
acceptSigma
MC acceptance
pre
the # PRE
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
acceptScale
SCALEDATA
MC acceptance
weight
REWEIGHT
weights of the weighted average
biasDer
REWEIGHT
derivatives with respect to the bias
scale
SCALEDATA
scale parameter
offset
ADDOFFSET
offset parameter
ftilde
GENERIC
ensemble average estimator
exp
ADDEXP
the # PRE experimental intensity
The atoms involved can be specified using
SPINLABEL
The atom to be used as the paramagnetic center.. For more information on how to specify lists
of atoms see Groups and Virtual Atoms
GROUPA
the atoms involved in each of the contacts you wish to calculate. Keywords like GROUPA1,
GROUPA2, GROUPA3,... should be listed and one contact will be calculated for each ATOM
keyword you specify. You can use multiple instances of this keyword i.e. GROUPA1, GROUPA2,
GROUPA3...
Compulsory keywords
NOISETYPE
( default=MGAUSS ) functional form of the noise (GAUSS,MGAUSS,OUTLIERS,MOUT←LIERS,GENERIC)
LIKELIHOOD
( default=GAUSS ) the likelihood for the GENERIC metainference model, GAUSS or LOGN
DFTILDE
( default=0.1 ) fraction of sigma_mean used to evolve ftilde
SCALE0
( default=1.0 ) initial value of the scaling factor
SCALE_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
OFFSET0
( default=0.0 ) initial value of the offset
OFFSET_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
SIGMA0
( default=1.0 ) initial value of the uncertainty parameter
SIGMA_MIN
( default=0.0 ) minimum value of the uncertainty parameter
SIGMA_MAX
( default=10. ) maximum value of the uncertainty parameter
OPTSIGMAMEAN
( default=NONE ) Set to NONE/SEM to manually set sigma mean, or to estimate it on the
fly
WRITE_STRIDE
INEPT
( default=10000 ) write the status to a file every N steps, this can be used for
restart/continuation
is the INEPT time (in ms).
TAUC
is the correlation time (in ns) for this electron-nuclear interaction.
OMEGA
is the Larmor frequency of the nuclear spin (in MHz).
Generated by Doxygen
478
Additional Modules
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
DOSCORE
( default=off ) activate metainference
NOENSEMBLE
( default=off ) don't perform any replica-averaging
REWEIGHT
( default=off ) simple REWEIGHT using the ARG as energy
SCALEDATA
( default=off ) Set to TRUE if you want to sample a scaling factor common to all
values and replicas
ADDOFFSET
( default=off ) Set to TRUE if you want to sample an offset common to all values
and replicas
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Set to TRUE if you want to have fixed components with the experimental values.
ADDEXP
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
AVERAGING
Stride for calculation of averaged weights and sigma_mean
SCALE_MIN
minimum value of the scaling factor
SCALE_MAX
maximum value of the scaling factor
DSCALE
maximum MC move of the scaling factor
OFFSET_MIN
OFFSET_MAX
DOFFSET
REGRES_ZERO
minimum value of the offset
maximum value of the offset
maximum MC move of the offset
stride for regression with zero offset
DSIGMA
maximum MC move of the uncertainty parameter
SIGMA_MEAN0
starting value for the uncertainty in the mean estimate
TEMP
the system temperature - this is only needed if code doesn't pass the temperature to plumed
MC_STEPS
number of MC steps
MC_STRIDE
MC_CHUNKSIZE
STATUS_FILE
SELECTOR
NSELECT
MC stride
MC chunksize
write a file with all the data useful for restart/continuation of Metainference
name of selector
range of values for selector [0, N-1]
RESTART
allows per-action setting of restart (YES/NO/AUTO)
RTWO
The relaxation of the atom/atoms in the corresponding GROUPA of atoms. Keywords like RTWO1, RTWO2, RTWO3,... should be listed. You can use multiple
instances of this keyword i.e. RTWO1, RTWO2, RTWO3...
Generated by Doxygen
8.1 PLUMED-ISDB
PREINT
479
Add an experimental value for each PRE. You can use multiple instances of
this keyword i.e. PREINT1, PREINT2, PREINT3...
Examples
In the following example five PRE intensities are calculated using the distance between the oxygen of the spin label
and the backbone hydrogen atoms. Omega is the NMR frequency, RTWO the R2 for the hydrogen atoms, INEPT
of 8 ms for the experiment and a TAUC of 1.21 ns
BEGIN_PLUMED_FILE
PRE ...
LABEL=HN_pre
INEPT=8
TAUC=1.21
OMEGA=900
SPINLABEL=1818
GROUPA1=86 RTWO1=0.0120272827
GROUPA2=177 RTWO2=0.0263953158
GROUPA3=285 RTWO3=0.0058899829
GROUPA4=335 RTWO4=0.0102072646
GROUPA5=451 RTWO5=0.0086341843
... PRE
PRINT ARG=HN_pre.* FILE=PRE.dat STRIDE=1
8.1.1.8
RDC
This is part of the isdb module
Calculates the (Residual) Dipolar Coupling between two atoms.
The Dipolar Coupling between two nuclei depends on the θ angle between the inter-nuclear vector and the external
magnetic field.
D = Dmax 0.5(3 cos2 (θ) − 1)
where
Dmax = −µ0 γ1 γ2 h/(8π 3 r3 )
that is the maximal value of the dipolar coupling for the two nuclear spins with gyromagnetic ratio γ . µ is the
magnetic constant and h is the Planck constant.
Common Gyromagnetic Ratios (C.G.S)
• H(1) 26.7513
• C(13) 6.7261
• N(15) -2.7116 and their products (this is what is given in input using the keyword GYROM)
• N-H -72.5388
Generated by Doxygen
480
Additional Modules
• C-H 179.9319
• C-N -18.2385
• C-C 45.2404
In isotropic media DCs average to zero because of the rotational averaging, but when the rotational symmetry is
broken, either through the introduction of an alignment medium or for molecules with highly anisotropic paramagnetic susceptibility, then the average of the DCs is not zero and it is possible to measure a Residual Dipolar Coupling
(RDCs).
This collective variable calculates the Dipolar Coupling for a set of couple of atoms using the above definition.
In a standard MD simulation the average over time of the DC should then be zero. If one wants to model the
meaning of a set of measured RDCs it is possible to try to solve the following problem: "what is the distribution of
structures and orientations that reproduce the measured RDCs".
This collective variable can then be use to break the rotational symmetry of a simulation by imposing that the
average of the DCs over the conformational ensemble must be equal to the measured RDCs [78] . Since measured
RDCs are also a function of the fraction of aligned molecules in the sample it is better to compare them modulo a
constant or looking at the correlation.
Alternatively if the molecule is rigid it is possible to use the experimental data to calculate the alignment tensor and
the use that to back calculate the RDCs, this is what is usually call the Single Value Decomposition approach. In
this case the code rely on the a set of function from the GNU Scientific Library (GSL). (With SVD forces are not
currently implemented).
Replica-Averaged simulations can be performed using RDCs, ENSEMBLE, STATS and RESTRAINT .
METAINFERENCE can be activated using DOSCORE and the other relevant keywords.
Additional material and examples can be also found in the tutorial Belfast tutorial: NMR restraints
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Quantity
Description
sigma
uncertainty parameter
sigmaMean
uncertainty in the mean estimate
acceptSigma
MC acceptance
rdc
the calculated # RDC
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
acceptScale
SCALEDATA
MC acceptance
weight
REWEIGHT
weights of the weighted average
biasDer
REWEIGHT
derivatives with respect to the bias
scale
SCALEDATA
scale parameter
offset
ADDOFFSET
offset parameter
ftilde
GENERIC
ensemble average estimator
Generated by Doxygen
8.1 PLUMED-ISDB
481
exp
SVD/ADDCOUPLINGS
the experimental # RDC
The atoms involved can be specified using
ATOMS
the couple of atoms involved in each of the bonds for which you wish to calculate the RDC. Keywords
like ATOMS1, ATOMS2, ATOMS3,... should be listed and one dipolar coupling will be calculated for
each ATOMS keyword you specify. You can use multiple instances of this keyword i.e. ATOMS1,
ATOMS2, ATOMS3...
Compulsory keywords
NOISETYPE
( default=MGAUSS ) functional form of the noise (GAUSS,MGAUSS,OUTLIERS,MOUT←LIERS,GENERIC)
LIKELIHOOD
( default=GAUSS ) the likelihood for the GENERIC metainference model, GAUSS or LOGN
DFTILDE
( default=0.1 ) fraction of sigma_mean used to evolve ftilde
SCALE0
( default=1.0 ) initial value of the scaling factor
SCALE_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
OFFSET0
( default=0.0 ) initial value of the offset
OFFSET_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
SIGMA0
( default=1.0 ) initial value of the uncertainty parameter
SIGMA_MIN
( default=0.0 ) minimum value of the uncertainty parameter
SIGMA_MAX
( default=10. ) maximum value of the uncertainty parameter
OPTSIGMAMEAN
( default=NONE ) Set to NONE/SEM to manually set sigma mean, or to estimate it on the
fly
WRITE_STRIDE
GYROM
( default=10000 ) write the status to a file every N steps, this can be used for
restart/continuation
( default=1. ) Add the product of the gyromagnetic constants for the bond.
SCALE
( default=1. ) Add the scaling factor to take into account concentration and other effects.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
DOSCORE
( default=off ) activate metainference
NOENSEMBLE
( default=off ) don't perform any replica-averaging
REWEIGHT
( default=off ) simple REWEIGHT using the ARG as energy
SCALEDATA
( default=off ) Set to TRUE if you want to sample a scaling factor common to all
values and replicas
ADDOFFSET
( default=off ) Set to TRUE if you want to sample an offset common to all values
and replicas
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Set to TRUE if you want to back calculate using Single Value
Decomposition (need GSL at compilation time).
SVD
ADDCOUPLINGS
Generated by Doxygen
( default=off ) Set to TRUE if you want to have fixed components with the experimental values.
482
Additional Modules
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
AVERAGING
Stride for calculation of averaged weights and sigma_mean
SCALE_MIN
minimum value of the scaling factor
SCALE_MAX
maximum value of the scaling factor
DSCALE
maximum MC move of the scaling factor
OFFSET_MIN
OFFSET_MAX
DOFFSET
REGRES_ZERO
minimum value of the offset
maximum value of the offset
maximum MC move of the offset
stride for regression with zero offset
DSIGMA
maximum MC move of the uncertainty parameter
SIGMA_MEAN0
starting value for the uncertainty in the mean estimate
TEMP
the system temperature - this is only needed if code doesn't pass the temperature to plumed
MC_STEPS
number of MC steps
MC_STRIDE
MC_CHUNKSIZE
STATUS_FILE
SELECTOR
NSELECT
MC stride
MC chunksize
write a file with all the data useful for restart/continuation of Metainference
name of selector
range of values for selector [0, N-1]
RESTART
allows per-action setting of restart (YES/NO/AUTO)
COUPLING
Add an experimental value for each coupling (needed by SVD and useful for
STATS). You can use multiple instances of this keyword i.e. COUPLING1,
COUPLING2, COUPLING3...
Examples
In the following example five N-H RDCs are defined and averaged over multiple replicas, their correlation is then
calculated with respect to a set of experimental data and restrained. In addition, and only for analysis purposes,
the same RDCs each single conformation are calculated using a Single Value Decomposition algorithm, then
averaged and again compared with the experimental data.
BEGIN_PLUMED_FILE
RDC ...
GYROM=-72.5388
SCALE=0.001
ATOMS1=20,21
ATOMS2=37,38
ATOMS3=56,57
ATOMS4=76,77
ATOMS5=92,93
LABEL=nh
... RDC
Generated by Doxygen
8.1 PLUMED-ISDB
483
erdc: ENSEMBLE ARG=nh.*
st: STATS ARG=erdc.* PARAMETERS=8.17,-8.271,-10.489,-9.871,-9.152
rdce: RESTRAINT ARG=st.corr KAPPA=0. SLOPE=-25000.0 AT=1.
RDC ...
GYROM=-72.5388
SVD
ATOMS1=20,21 COUPLING1=8.17
ATOMS2=37,38 COUPLING2=-8.271
ATOMS3=56,57 COUPLING3=-10.489
ATOMS4=76,77 COUPLING4=-9.871
ATOMS5=92,93 COUPLING5=-9.152
LABEL=svd
... RDC
esvd: ENSEMBLE ARG=svd.*
st_svd: STATS ARG=esvd.* PARAMETERS=8.17,-8.271,-10.489,-9.871,-9.152
PRINT ARG=st.corr,st_svd.corr,rdce.bias FILE=colvar
8.1.1.9
SAXS
This is part of the isdb module
Calculates SAXS scattered intensity using either the Debye equation or the harmonic sphere approximation.
Intensities are calculated for a set of scattering length set using QVALUE keywords that are numbered starting from
0. Structure factors can be either assigned using a polynomial expansion to any order using the PARAMETERS
keywords; automatically assigned to atoms using the ATOMISTIC flag reading a PDB file, a correction for the water
density is automatically added, with water density that by default is 0.334 but that can be set otherwise using WA←TERDENS; automatically assigned to Martini pseudo atoms using the MARTINI flag. The calculated intensities can
be scaled using the SCALEINT keywords. This is applied by rescaling the structure factors. Experimental reference
intensities can be added using the EXPINT keywords. By default SAXS is calculated using Debye on CPU, by
adding the GPU flag it is possible to solve the equation on a GPU if the ARRAYFIRE libraries are installed and
correctly linked (). Alternatively we an implementation based on Bessel functions, BESSEL flag. This is very fast
for small q values because a short expansion is enough. An automatic choice is made for which q Bessel are used
and for which the calculation is done by Debye. If one wants to force all q values to be calculated using Bessel
function this can be done using FORCE_BESSEL. Irrespective of the method employed, METAINFERENCE can
be activated using DOSCORE and the other relevant keywords.
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Generated by Doxygen
Quantity
Description
sigma
uncertainty parameter
sigmaMean
uncertainty in the mean estimate
acceptSigma
MC acceptance
q
the # SAXS of q
484
Additional Modules
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
acceptScale
SCALEDATA
MC acceptance
weight
REWEIGHT
weights of the weighted average
biasDer
REWEIGHT
derivatives with respect to the bias
scale
SCALEDATA
scale parameter
offset
ADDOFFSET
offset parameter
ftilde
GENERIC
ensemble average estimator
exp
EXPINT
the # experimental intensity
The atoms involved can be specified using
ATOMS
The atoms to be included in the calculation, e.g. the whole protein.. For more information on how to
specify lists of atoms see Groups and Virtual Atoms
Compulsory keywords
NOISETYPE
( default=MGAUSS ) functional form of the noise (GAUSS,MGAUSS,OUTLIERS,MOUT←LIERS,GENERIC)
LIKELIHOOD
( default=GAUSS ) the likelihood for the GENERIC metainference model, GAUSS or LOGN
DFTILDE
( default=0.1 ) fraction of sigma_mean used to evolve ftilde
SCALE0
( default=1.0 ) initial value of the scaling factor
SCALE_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
OFFSET0
( default=0.0 ) initial value of the offset
OFFSET_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
SIGMA0
( default=1.0 ) initial value of the uncertainty parameter
SIGMA_MIN
( default=0.0 ) minimum value of the uncertainty parameter
SIGMA_MAX
( default=10. ) maximum value of the uncertainty parameter
OPTSIGMAMEAN
( default=NONE ) Set to NONE/SEM to manually set sigma mean, or to estimate it on the
fly
WRITE_STRIDE
( default=10000 ) write the status to a file every N steps, this can be used for
restart/continuation
( default=0 ) Identifier of the GPU to be used
DEVICEID
WATERDENS
SCALEINT
( default=0.334 ) Density of the water to be used for the correction of atomistic structure
factors.
( default=1.0 ) SCALING value of the calculated data. Useful to simplify the comparison.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
DOSCORE
( default=off ) activate metainference
NOENSEMBLE
( default=off ) don't perform any replica-averaging
REWEIGHT
( default=off ) simple REWEIGHT using the ARG as energy
Generated by Doxygen
8.1 PLUMED-ISDB
485
SCALEDATA
( default=off ) Set to TRUE if you want to sample a scaling factor common to all
values and replicas
ADDOFFSET
( default=off ) Set to TRUE if you want to sample an offset common to all values
and replicas
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Perform the calculation in serial - for debug purpose
SERIAL
BESSEL
( default=off ) Perform the calculation using the adaptive spherical harmonic
approximation
FORCE_BESSEL
( default=off ) Perform the calculation using the adaptive spherical harmonic
approximation, without adaptive algorithm, useful for debug only
GPU
( default=off ) calculate SAXS using ARRAYFIRE on an accelerator device
ATOMISTIC
( default=off ) calculate SAXS for an atomistic model
MARTINI
( default=off ) calculate SAXS for a Martini model
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
AVERAGING
Stride for calculation of averaged weights and sigma_mean
SCALE_MIN
minimum value of the scaling factor
SCALE_MAX
maximum value of the scaling factor
DSCALE
maximum MC move of the scaling factor
OFFSET_MIN
OFFSET_MAX
DOFFSET
REGRES_ZERO
minimum value of the offset
maximum value of the offset
maximum MC move of the offset
stride for regression with zero offset
DSIGMA
maximum MC move of the uncertainty parameter
SIGMA_MEAN0
starting value for the uncertainty in the mean estimate
TEMP
the system temperature - this is only needed if code doesn't pass the temperature to plumed
MC_STEPS
number of MC steps
MC_STRIDE
MC_CHUNKSIZE
STATUS_FILE
SELECTOR
NSELECT
MC stride
MC chunksize
write a file with all the data useful for restart/continuation of Metainference
name of selector
range of values for selector [0, N-1]
RESTART
allows per-action setting of restart (YES/NO/AUTO)
QVALUE
Selected scattering lengths in Angstrom are given as QVALUE1, QVALUE2, ...
. You can use multiple instances of this keyword i.e. QVALUE1, QVALUE2,
QVALUE3...
Generated by Doxygen
486
Additional Modules
PARAMETERS
Used parameter Keywords like PARAMETERS1, PARAMETERS2. These are
used to calculate the structure factor for the ith atom/bead. You can use multiple instances of this keyword i.e. PARAMETERS1, PARAMETERS2, PARA←METERS3...
Add an experimental value for each q value. You can use multiple instances of
this keyword i.e. EXPINT1, EXPINT2, EXPINT3...
EXPINT
Examples
in the following example the saxs intensities for a martini model are calculated. structure factors are obtained
from the pdb file indicated in the MOLINFO.
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=template.pdb
SAXS ...
LABEL=saxs
ATOMS=1-355
SCALEINT=3920000
MARTINI
QVALUE1=0.02 EXPINT1=1.0902
QVALUE2=0.05 EXPINT2=0.790632
QVALUE3=0.08 EXPINT3=0.453808
QVALUE4=0.11 EXPINT4=0.254737
QVALUE5=0.14 EXPINT5=0.154928
QVALUE6=0.17 EXPINT6=0.0921503
QVALUE7=0.2 EXPINT7=0.052633
QVALUE8=0.23 EXPINT8=0.0276557
QVALUE9=0.26 EXPINT9=0.0122775
QVALUE10=0.29 EXPINT10=0.00880634
QVALUE11=0.32 EXPINT11=0.0137301
QVALUE12=0.35 EXPINT12=0.0180036
QVALUE13=0.38 EXPINT13=0.0193374
QVALUE14=0.41 EXPINT14=0.0210131
QVALUE15=0.44 EXPINT15=0.0220506
... SAXS
PRINT ARG=(saxs\.q_.*),(saxs\.exp_.*) FILE=colvar STRIDE=1
8.1.2
Functions Documentation
The following list contains descriptions of functions originally developed for the PLUMED-ISDB module. They can
be used in combination with any other collective variable, function or bias also outside the ISDB module.
SELECT
8.1.2.1
Selects an argument based on the value of a SELECTOR.
SELECT
This is part of the isdb module
Selects an argument based on the value of a SELECTOR.
Compulsory keywords
Generated by Doxygen
8.1 PLUMED-ISDB
487
SELECTOR
name of the variable used to select
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
In this example we use a simulated-tempering like approach activated by the RESCALE action. For each value
of the scale parameter, we perform an independent Parallel Bias Metadynamics simulation (see PBMETAD). At
each moment of the simulation, only one of the PBMETAD actions is activated, based on the current value of the
associated SELECTOR. The SELECT action can then be used to print out the value of the (active) PBMETAD bias
potential.
BEGIN_PLUMED_FILE
ene: ENERGY
d: DISTANCE ATOMS=1,2
SELECTOR NAME=GAMMA VALUE=0
pbmetad0: PBMETAD ARG=d SELECTOR=GAMMA SELECTOR_ID=0 SIGMA=0.1 PACE=500 HEIGHT=1 BIASFACTOR=8 FILE=HILLS.0
pbmetad1: PBMETAD ARG=d SELECTOR=GAMMA SELECTOR_ID=1 SIGMA=0.1 PACE=500 HEIGHT=1 BIASFACTOR=8 FILE=HILLS.1
RESCALE ...
LABEL=res ARG=ene,pbmetad0.bias,pbmetad1.bias TEMP=300
SELECTOR=GAMMA MAX_RESCALE=1.2 NOT_RESCALED=2 NBIN=2
W0=1000 BIASFACTOR=100.0 BSTRIDE=2000 BFILE=bias.dat
...
pbactive: SELECT ARG=pbmetad0.bias,pbmetad1.bias SELECTOR=GAMMA
PRINT ARG=pbactive STRIDE=100 FILE=COLVAR
8.1.3
Biases Documentation
The following list contains descriptions of biases originally developed for the PLUMED-ISDB module. They can be
used in combination with any other collective variable, function or bias also outside the ISDB module.
Generated by Doxygen
488
Additional Modules
CALIBER
Add a time-dependent, harmonic restraint on one or more variables.This allows implementing a maximum caliber restraint on one or more experimental time series by replicaaveraged restrained simulations.See [35] .
METAINFERENCE
Calculates the Metainference energy for a set of experimental data.
RESCALE
Scales the value of an another action, being a Collective Variable or a Bias.
8.1.3.1
CALIBER
This is part of the isdb module
Add a time-dependent, harmonic restraint on one or more variables. This allows implementing a maximum caliber
restraint on one or more experimental time series by replica-averaged restrained simulations. See [35] .
The time resolved experiments are read from a text file and intermediate values are obtained by splines.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
x0
the instantaneous value of the center of the potential
mean
the current average value of the calculated observable
kappa
the current force constant
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
scale
REGRES_ZERO
the current scaling constant
Compulsory keywords
FILE
the name of the file containing the time-resolved values
KAPPA
a force constant, this can be use to scale a constant estimated on-the-fly using AVERAGING
TSCALE
( default=1.0 ) Apply a time scaling on the experimental time scale
SCALE
( default=1.0 ) Apply a constant scaling on the data provided as arguments
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
Generated by Doxygen
8.1 PLUMED-ISDB
489
NOENSEMBLE
( default=off ) don't perform any replica-averaging
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
AVERAGING
Stride for calculation of the optimum kappa, if 0 only KAPPA is used.
REGRES_ZERO
stride for regression with zero offset
Examples
In the following example a restraint is applied on the time evolution of a saxs spectrum
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=first.pdb
# Define saxs variable
SAXS ...
LABEL=saxs
ATOMISTIC
ATOMS=1-436
QVALUE1=0.02 # Q-value at which calculate the scattering
QVALUE2=0.0808
QVALUE3=0.1264
QVALUE4=0.1568
QVALUE5=0.172
QVALUE6=0.1872
QVALUE7=0.2176
QVALUE8=0.2328
QVALUE9=0.248
QVALUE10=0.2632
QVALUE11=0.2936
QVALUE12=0.3088
QVALUE13=0.324
QVALUE14=0.3544
QVALUE15=0.4
... SAXS
#define the caliber restraint
CALIBER ...
ARG=(saxs\.q_.*)
FILE=expsaxs.dat
KAPPA=10
LABEL=cal0
STRIDE=10
REGRES_ZERO=200
AVERAGING=200
... CALIBER
Generated by Doxygen
490
Additional Modules
In particular the file expsaxs.dat contains the time traces for the 15 intensities at the selected scattering lengths,
organized as time, q_1, etc. The strength of the bias is automatically evaluated from the standard error of the mean
over AVERAGING steps and multiplied by KAPPA. This is useful when working with multiple experimental data
Because SAXS is usually defined in a manner that is irrespective of a scaling factor the scaling is evaluated from a
linear fit every REGRES_ZERO step. Alternatively it can be given as a fixed constant as SCALE. The bias is here
applied every tenth step.
8.1.3.2
METAINFERENCE
This is part of the isdb module
Calculates the Metainference energy for a set of experimental data.
Metainference [76] is a Bayesian framework to model heterogeneous systems by integrating prior information with
noisy, ensemble-averaged data. Metainference models a system and quantifies the level of noise in the data by
considering a set of replicas of the system.
Calculated experimental data are given in input as ARG while reference experimental values can be given either
from fixed components of other actions using PARARG or as numbers using PARAMETERS. The default behavior
is that of averaging the data over the available replicas, if this is not wanted the keyword NOENSEMBLE prevent
this averaging.
Metadynamics Metainference [79] or more in general biased Metainference requires the knowledge of biasing potential in order to calculate the weighted average. In this case the value of the bias can be provided as the last
argument in ARG and adding the keyword REWEIGHT. To avoid the noise resulting from the instantaneous value
of the bias the weight of each replica can be averaged over a give time using the keyword AVERAGING.
The data can be averaged by using multiple replicas and weighted for a bias if present. The functional form of
Metainference can be chosen among four variants selected with NOISE=GAUSS,MGAUSS,OUTLIERS,MOUTL←IERS,GENERIC which correspond to modelling the noise for the arguments as a single gaussian common to all
the data points, a gaussian per data point, a single long-tailed gaussian common to all the data points, a log-tailed
gaussian per data point or using two distinct noises as for the most general formulation of Metainference. In this
latter case the noise of the replica-averaging is gaussian (one per data point) and the noise for the comparison with
the experimental data can chosen using the keyword LIKELIHOOD between gaussian or log-normal (one per data
point), furthermore the evolution of the estimated average over an infinite number of replicas is driven by DFTILDE.
As for Metainference theory there are two sigma values: SIGMA_MEAN represent the error of calculating an average quantity using a finite set of replica and should be set as small as possible following the guidelines for
replica-averaged simulations in the framework of the Maximum Entropy Principle. Alternatively, this can be obtained
automatically using the internal sigma mean optimization as introduced in [80] (OPTSIGMAMEAN=SEM), in this
second case sigma_mean is estimated from the maximum standard error of the mean either over the simulation or
over a defined time using the keyword AVERAGING. SIGMA_BIAS is an uncertainty parameter, sampled by a MC
algorithm in the bounded interval defined by SIGMA_MIN and SIGMA_MAX. The initial value is set at SIGMA0. The
MC move is a random displacement of maximum value equal to DSIGMA. If the number of data point is too large and
the acceptance rate drops it is possible to make the MC move over mutually exclusive, random subset of size MC←_CHUNKSIZE and run more than one move setting MC_STRIDE in such a way that MC_CHUNKSIZE∗MC_STEPS
will cover all the data points.
Calculated and experimental data can be compared modulo a scaling factor and/or an offset using SCALEDATA
and/or ADDOFFSET, the sampling is obtained by a MC algorithm either using a flat or a gaussian prior setting it
with SCALE_PRIOR or OFFSET_PRIOR.
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Generated by Doxygen
8.1 PLUMED-ISDB
491
Quantity
Description
bias
the instantaneous value of the bias potential
sigma
uncertainty parameter
sigmaMean
uncertainty in the mean estimate
acceptSigma
MC acceptance
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
acceptScale
SCALEDATA
MC acceptance
weight
REWEIGHT
weights of the weighted average
biasDer
REWEIGHT
derivatives with respect to the bias
scale
SCALEDATA
scale parameter
offset
ADDOFFSET
offset parameter
ftilde
GENERIC
ensemble average estimator
Compulsory keywords
NOISETYPE
( default=MGAUSS ) functional form of the noise (GAUSS,MGAUSS,OUTLIERS,MOUT←LIERS,GENERIC)
LIKELIHOOD
( default=GAUSS ) the likelihood for the GENERIC metainference model, GAUSS or LOGN
DFTILDE
( default=0.1 ) fraction of sigma_mean used to evolve ftilde
SCALE0
( default=1.0 ) initial value of the scaling factor
SCALE_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
OFFSET0
( default=0.0 ) initial value of the offset
OFFSET_PRIOR
( default=FLAT ) either FLAT or GAUSSIAN
SIGMA0
( default=1.0 ) initial value of the uncertainty parameter
SIGMA_MIN
( default=0.0 ) minimum value of the uncertainty parameter
SIGMA_MAX
( default=10. ) maximum value of the uncertainty parameter
OPTSIGMAMEAN
( default=NONE ) Set to NONE/SEM to manually set sigma mean, or to estimate it on the
fly
WRITE_STRIDE
( default=10000 ) write the status to a file every N steps, this can be used for
restart/continuation
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOENSEMBLE
( default=off ) don't perform any replica-averaging
REWEIGHT
( default=off ) simple REWEIGHT using the latest ARG as energy
SCALEDATA
( default=off ) Set to TRUE if you want to sample a scaling factor common to all
values and replicas
ADDOFFSET
( default=off ) Set to TRUE if you want to sample an offset common to all values
and replicas
Generated by Doxygen
492
Additional Modules
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
PARARG
PARAMETERS
reference values for the experimental data, these can be provided as arguments without derivatives
reference values for the experimental data
AVERAGING
Stride for calculation of averaged weights and sigma_mean
SCALE_MIN
minimum value of the scaling factor
SCALE_MAX
maximum value of the scaling factor
DSCALE
maximum MC move of the scaling factor
OFFSET_MIN
OFFSET_MAX
DOFFSET
REGRES_ZERO
minimum value of the offset
maximum value of the offset
maximum MC move of the offset
stride for regression with zero offset
DSIGMA
maximum MC move of the uncertainty parameter
SIGMA_MEAN0
starting value for the uncertainty in the mean estimate
TEMP
the system temperature - this is only needed if code doesn't pass the temperature to plumed
MC_STEPS
number of MC steps
MC_STRIDE
MC_CHUNKSIZE
STATUS_FILE
SELECTOR
NSELECT
MC stride
MC chunksize
write a file with all the data useful for restart/continuation of Metainference
name of selector
range of values for selector [0, N-1]
RESTART
allows per-action setting of restart (YES/NO/AUTO)
Examples
In the following example we calculate a set of RDC, take the replica-average of them and comparing them with a
set of experimental values. RDCs are compared with the experimental data but for a multiplication factor SCALE
that is also sampled by MC on-the-fly
BEGIN_PLUMED_FILE
RDC ...
LABEL=rdc
SCALE=0.0001
GYROM=-72.5388
ATOMS1=22,23
ATOMS2=25,27
ATOMS3=29,31
ATOMS4=33,34
Generated by Doxygen
8.1 PLUMED-ISDB
493
... RDC
METAINFERENCE ...
ARG=rdc.*
NOISETYPE=MGAUSS
PARAMETERS=1.9190,2.9190,3.9190,4.9190
SCALEDATA SCALE0=1 SCALE_MIN=0.1 SCALE_MAX=3 DSCALE=0.01
SIGMA0=0.01 SIGMA_MIN=0.00001 SIGMA_MAX=3 DSIGMA=0.01
SIGMA_MEAN=0.001
LABEL=spe
... METAINFERENCE
PRINT ARG=spe.bias FILE=BIAS STRIDE=1
in the following example instead of using one uncertainty parameter per data point we use a single uncertainty value
in a long-tailed gaussian to take into account for outliers, furthermore the data are weighted for the bias applied to
other variables of the system.
BEGIN_PLUMED_FILE
cv1: TORSION ATOMS=1,2,3,4
cv2: TORSION ATOMS=2,3,4,5
mm: METAD ARG=cv1,cv2 HEIGHT=0.5 SIGMA=0.3,0.3 PACE=200 BIASFACTOR=8 WALKERS_MPI
METAINFERENCE ...
ARG=rdc.*,mm.bias
REWEIGHT
NOISETYPE=OUTLIERS
PARAMETERS=1.9190,2.9190,3.9190,4.9190
SCALEDATA SCALE0=1 SCALE_MIN=0.1 SCALE_MAX=3 DSCALE=0.01
SIGMA0=0.01 SIGMA_MIN=0.00001 SIGMA_MAX=3 DSIGMA=0.01
SIGMA_MEAN=0.001
LABEL=spe
... METAINFERENCE
(See also RDC, PBMETAD).
8.1.3.3
RESCALE
This is part of the isdb module
Scales the value of an another action, being a Collective Variable or a Bias.
The rescaling factor is determined by a parameter defined on a logarithmic grid of dimension NBIN in the range from
1 to MAX_RESCALE. The current value of the rescaling parameter is stored and shared across other actions using
a SELECTOR. A Monte Carlo procedure is used to update the value of the rescaling factor every MC_STRIDE steps
of molecular dynamics. Well-tempered metadynamics, defined by the parameters W0 and BIASFACTOR, is used to
enhance the sampling in the space of the rescaling factor. The well-tempered metadynamics bias potential is written
to the file BFILE every BSTRIDE steps and read when restarting the simulation using the directive RESTART.
Note
Additional arguments not to be scaled, one for each bin in the rescaling parameter ladder, can be provided at
the end of the ARG list. The number of such arguments is specified by the option NOT_RESCALED. These
arguments will be not be scaled, but they will be considered as bias potentials and used in the computation
of the Metropolis acceptance probability when proposing a move in the rescaling parameter. See example
below.
If PLUMED is running in a multiple-replica framework (for example using the -multi option in GROMACS), the
arguments will be summed across replicas, unless the NOT_SHARED option is used. Also, the value of the
SELECTOR will be shared and thus will be the same in all replicas.
Generated by Doxygen
494
Additional Modules
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
igamma
gamma parameter
accgamma
MC acceptance for gamma
wtbias
well-tempered bias
Compulsory keywords
TEMP
temperature
SELECTOR
name of the SELECTOR used for rescaling
MAX_RESCALE
maximum values for rescaling
NBIN
number of bins for gamma grid
W0
initial bias height
BIASFACTOR
BSTRIDE
bias factor
stride for writing bias
BFILE
file name for bias
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
NOT_SHARED
list of arguments (from 1 to N) not summed across replicas
NOT_RESCALED
these last N arguments will not be scaled
MC_STEPS
number of MC steps
MC_STRIDE
PACE
MC stride
Pace for adding bias, in MC stride unit
Generated by Doxygen
8.1 PLUMED-ISDB
495
Examples
In this example we use RESCALE to implement a simulated-tempering like approach. The total potential energy
of the system is scaled by a parameter defined on a logarithmic grid of 5 bins in the range from 1 to 1.5. A welltempered metadynamics bias potential is used to ensure diffusion in the space of the rescaling parameter.
BEGIN_PLUMED_FILE
ene: ENERGY
SELECTOR NAME=GAMMA VALUE=0
RESCALE ...
LABEL=res ARG=ene TEMP=300
SELECTOR=GAMMA MAX_RESCALE=1.5 NBIN=5
W0=1000 BIASFACTOR=100.0 BSTRIDE=2000 BFILE=bias.dat
...
PRINT FILE=COLVAR ARG=* STRIDE=100
In this second example, we add to the simulated-tempering approach introduced above one Parallel Bias metadynamics simulation (see PBMETAD) for each value of the rescaling parameter. At each moment of the simulation,
only one of the PBMETAD actions is activated, based on the current value of the associated SELECTOR. The
PBMETAD bias potentials are not scaled, but just used in the calculation of the Metropolis acceptance probability
when proposing a move in the rescaling parameter.
BEGIN_PLUMED_FILE
ene: ENERGY
d: DISTANCE ATOMS=1,2
SELECTOR NAME=GAMMA VALUE=0
pbmetad0:
pbmetad1:
pbmetad2:
pbmetad3:
pbmetad4:
PBMETAD
PBMETAD
PBMETAD
PBMETAD
PBMETAD
ARG=d
ARG=d
ARG=d
ARG=d
ARG=d
SELECTOR=GAMMA
SELECTOR=GAMMA
SELECTOR=GAMMA
SELECTOR=GAMMA
SELECTOR=GAMMA
SELECTOR_ID=0
SELECTOR_ID=1
SELECTOR_ID=2
SELECTOR_ID=3
SELECTOR_ID=4
SIGMA=0.1
SIGMA=0.1
SIGMA=0.1
SIGMA=0.1
SIGMA=0.1
PACE=500
PACE=500
PACE=500
PACE=500
PACE=500
HEIGHT=1
HEIGHT=1
HEIGHT=1
HEIGHT=1
HEIGHT=1
BIASFACTOR=8
BIASFACTOR=8
BIASFACTOR=8
BIASFACTOR=8
BIASFACTOR=8
RESCALE ...
LABEL=res TEMP=300
ARG=ene,pbmetad0.bias,pbmetad1.bias,pbmetad2.bias,pbmetad3.bias,pbmetad4.bias
SELECTOR=GAMMA MAX_RESCALE=1.5 NOT_RESCALED=5 NBIN=5
W0=1000 BIASFACTOR=100.0 BSTRIDE=2000 BFILE=bias.dat
...
PRINT FILE=COLVAR ARG=* STRIDE=100
8.1.4
SELECTOR
This is part of the isdb module
Defines a variable (of the type double) inside the PLUMED code that can be used and modified by other actions.
A SELECTOR can be used for example to activate or modify a bias based on its current value.
Compulsory keywords
Generated by Doxygen
FILE=HILLS.0
FILE=HILLS.1
FILE=HILLS.2
FILE=HILLS.3
FILE=HILLS.4
496
Additional Modules
NAME
VALUE
name of the SELECTOR
set (initial) value of the SELECTOR
Examples
A typical example is the simulated-tempering like approach activated by RESCALE. In this example the total potential energy of the system is scaled by a parameter defined on a grid of dimension NBIN in the range from 1 to
MAX_RESCALE. The value of the scaling parameter is determined by the current value of the SELECTOR G←AMMA. The value of the SELECTOR is updated by a MC protocol inside the RESCALE class. A well-tempered
metadynamics potential is used to enhance sampling in the SELECTOR space.
BEGIN_PLUMED_FILE
ene: ENERGY
SELECTOR NAME=GAMMA VALUE=0
RESCALE ...
LABEL=res ARG=ene TEMP=300
SELECTOR=GAMMA MAX_RESCALE=1.2 NBIN=2
W0=1000 BIASFACTOR=100.0 BSTRIDE=2000 BFILE=bias.dat
...
PRINT FILE=COLVAR ARG=* STRIDE=100
8.1.5
Tutorials
The following are tutorials meant to learn how to use the different methods implemented in the ISDB module.
ISDB: setting up a Metadynamics Metainference simulation
This tutorial show an example on how to use PLUM←ED-ISDB to run Metadynamics Metainference
ISDB: setting up a SAXS post processing and refinement This
calculation
tutorial using
show an
MARTINI
example
form
on how
factors
to use PLUMEDISDB to run SAXS analysis and refinement calculation
8.1.5.1
8.1.5.1.1
ISDB: setting up a Metadynamics Metainference simulation
Aims
The aim of this tutorial is to introduce the users to the ISDB module and in particular to Metadynamics Metainference
[76] [79] ensemble determination. We will reproduce the setup of the simulation for a simple system [80] . For a
general overview of the problem of ensembles determination please read [81] .
8.1.5.1.2
Objectives
Once this tutorial is completed students will be able to:
• Setup their own PLUMED-ISDB simulation.
Generated by Doxygen
8.1 PLUMED-ISDB
8.1.5.1.3
497
Resources
TheTARBALL for this project contains the following files:
• charmm36-eef1sb.ff: the force-field files for gromacs (not needed)
• system: a folder with reference files for gromacs (not needed)
• reference-impl: a folder to perform a simple implicit solvent simulation
• reference-impl-pbmetad: a folder to perform a pbmetad implicit solvent simulation
• m_and_m: a folder to perform a metadynamics metainference simulation
This tutorial has been tested on a pre-release version of version 2.4.
8.1.5.1.4
Introduction
Molecular dynamics simulations are the ideal tool to determine at atomistic resolution the behavior of complex
molecules. This great resolution power comes at the cost of approximations that affects the agreement with actual
experimental observables. At the same time experimental data alone are generally speaking not enough to determine a structural ensemble due the inverse nature of the problem, that is to go from few observables to many
atoms in many different configurations. Furthermore, experimental data are affected by errors of multiple nature,
from noise, systematic errors and errors in their atomistic interpretation. Most important experimental data are the
result of the averaging over the ensemble of structure so it is not trivial to deconvolve this signal. One possibility is
that of employing MD simulations together with experimental data to generate simulations already corrected for the
data themselves. With METAINFERENCE this is done on-the-fly by adding an additional energy to the system that
takes into account the agreement with the experimental data considering the multiple sources of errors.
8.1.5.1.5
Run a reference simulation
The system we use is the EGAAWAASS peptide used in ref. [80] . First of all we will run a simulation in implicit
solvent using the EEF1-SB CHARMM36 force field. EEF1-SB includes a correction to the standard backbone
torsion potential of CHARMM36, an electrostatic interaction with a distance dependent dielectric constant and a
simple gaussian form for the solvation energy. The first two terms are implemented in the force field and using table
potentials while the latter is implemented as a collective variable in PLUMED, EEFSOLV .
BEGIN_PLUMED_FILE
# this is optional and tell to VIM that this is a PLUMED file
# vim: ft=plumed
# see comments just below this input file
MOLINFO MOLTYPE=protein STRUCTURE=egaawaass.pdb
WHOLEMOLECULES ENTITY0=1-111
# EEF1SB Implicit solvation
protein-h: GROUP NDX_FILE=index.ndx NDX_GROUP=Protein-H
solv: EEFSOLV ATOMS=protein-h NOPBC NL_STRIDE=10 NL_BUFFER=0.1
bias: BIASVALUE ARG=solv
This can be run using gromacs (unfortunately recent versions of gromacs do not support Verlet groups with table
potentials, so performances are currently sub-optimal on the gromacs side)
gmx_mpi mdrun -s run.tpr -table table.xvg -tablep table.xvg -plumed plumed-eef1.dat -v
In order to have a converged sampling for this reference ensemble calculation it is useful to setup a Metadynamics
calculation. In particular we will use PBMETAD because it is then a natural choice for Metadynamics Metainference
later. The following input file is meant to be appended to the former.
Generated by Doxygen
498
Additional Modules
BEGIN_PLUMED_FILE
# CVs, Psi9, Phi1 are not defined
psi1: TORSION ATOMS=@psi-1 NOPBC
psi2: TORSION ATOMS=@psi-2 NOPBC
psi3: TORSION ATOMS=@psi-3 NOPBC
psi4: TORSION ATOMS=@psi-4 NOPBC
psi5: TORSION ATOMS=@psi-5 NOPBC
psi6: TORSION ATOMS=@psi-6 NOPBC
psi7: TORSION ATOMS=@psi-7 NOPBC
psi8: TORSION ATOMS=@psi-8 NOPBC
phi2:
phi3:
phi4:
phi5:
phi6:
phi7:
phi8:
phi9:
TORSION
TORSION
TORSION
TORSION
TORSION
TORSION
TORSION
TORSION
ATOMS=@phi-2
ATOMS=@phi-3
ATOMS=@phi-4
ATOMS=@phi-5
ATOMS=@phi-6
ATOMS=@phi-7
ATOMS=@phi-8
ATOMS=@phi-9
NOPBC
NOPBC
NOPBC
NOPBC
NOPBC
NOPBC
NOPBC
NOPBC
ahc:
ALPHARMSD RESIDUES=all TYPE=OPTIMAL LESS_THAN={RATIONAL R_0=0.12}
# Bulky Trp residue dihedral
dihtrp_cacb: TORSION ATOMS=67,47,49,52 NOPBC
dihtrp_cbcg: TORSION ATOMS=47,49,52,53 NOPBC
protein-ca: GROUP NDX_FILE=index.ndx NDX_GROUP=C-alpha
gyr: GYRATION TYPE=RADIUS ATOMS=protein-ca NOPBC
# PBMetaD
PBMETAD ...
LABEL=pb
ARG=phi2,phi3,phi4,phi5,phi6,phi7,phi8,phi9,psi1,psi2,psi3,psi4,psi5,psi6,psi7,psi8,dihtrp_cacb,dihtrp_cbc
SIGMA=1000
SIGMA_MIN=0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.06,0.001
SIGMA_MAX=0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.6,0.2
ADAPTIVE=DIFF
HEIGHT=0.5
PACE=200
BIASFACTOR=40
GRID_MIN=-pi,-pi,-pi,-pi,-pi,-pi,-pi,-pi,-pi,-pi,-pi,-pi,-pi,-pi,-pi,-pi,-pi,-pi,0
GRID_MAX=pi,pi,pi,pi,pi,pi,pi,pi,pi,pi,pi,pi,pi,pi,pi,pi,pi,pi,5
GRID_WSTRIDE=5000
WALKERS_MPI
... PBMETAD
PRINT FILE=COLVAR ARG=phi2,phi3,phi4,phi5,phi6,phi7,phi8,phi9,psi1,psi2,psi3,psi4,psi5,psi6,psi7,psi8,dihtrp_c
PRINT FILE=ENERGY ARG=bias.bias,pb.bias STRIDE=200
In this case we are running a multiple-replica simulation where the sampling is used to parallelize the Metadynamics
time-dependent potential through the use of multiple walkers.
mpiexec -np 14 gmx_mpi mdrun -s topolnew -multi 14 -plumed plumed-eef1-pbmetad.dat -table table.xvg -tablep ta
8.1.5.1.6
Metadynamics Metainference
The former simulations should provide a converged (check for this) ensemble for the peptide. As shown in [80]
the agreement with the multiple available NMR experimental data is not perfect. In order to generate an ensemble compatible with most of the available experimental data it is possible to include them in the simulation using
METAINFERENCE . To do so the forward models for the data sets should be defined in the input file. In this
case we have backbone chemical shifts, CS2BACKBONE ; residual dipolar couplings for two bonds, RDC ; and
J-couplings for multiple atoms, JCOUPLING. Once the forward models are defined for the data sets, the calculated
data together with the corresponding experimental values can be used to calculate the metainference score. The
metainference score is additive so it can be split into multiple METAINFERENCE entries. In this case we are using
two metainference entries for the two sets of RDCs because these are compared with the experimental data modulo
a constant that should be unique each data set. Then we use one metainference for all the jcouplings and another
Generated by Doxygen
8.1 PLUMED-ISDB
499
one for the chemical shifts. In this latter case we use a different noise model, i.e. NOISE=MOUTLIERS because
the forward model for chemical shifts can result in systematic errors for some of them.
The following input file is meant to be appended to the former files.
BEGIN_PLUMED_FILE
# EXPERIMENTAL DATA SECTION
# RDCs (Grzesiek et al.)
# xGAAWAASS
RDC ...
ADDCOUPLINGS
GYROM=-72.5388
SCALE=0.0001
NOPBC
ATOMS1=18,19 COUPLING1=-5.4
ATOMS2=25,26 COUPLING2=-1.26
ATOMS3=35,36 COUPLING3=-5.22
ATOMS4=45,46 COUPLING4=-0.91
ATOMS5=69,70 COUPLING5=2.33
ATOMS6=79,80 COUPLING6=-2.88
ATOMS7=89,90 COUPLING7=-8.37
ATOMS8=100,101 COUPLING8=-3.78
LABEL=nh
... RDC
# ExAAWAASx
RDC ...
ADDCOUPLINGS
GYROM=179.9319
SCALE=0.0001
NOPBC
ATOMS1=5,6 COUPLING1=12.95
ATOMS2=27,28 COUPLING2=11.5
ATOMS3=37,38 COUPLING3=21.42
ATOMS4=47,48 COUPLING4=-9.37
ATOMS5=71,72 COUPLING5=10.01
ATOMS6=81,82 COUPLING6=15.01
ATOMS7=91,92 COUPLING7=15.73
LABEL=caha
... RDC
# xGxAWxASx
JCOUPLING ...
ADDCOUPLINGS
TYPE=HAN
NOPBC
ATOMS1=@psi-2
ATOMS2=@psi-4
ATOMS3=@psi-5
ATOMS4=@psi-7
ATOMS5=@psi-8
LABEL=jhan
... JCOUPLING
# xxAAWAASS
JCOUPLING ...
ADDCOUPLINGS
TYPE=HAHN
NOPBC
ATOMS1=@phi-2
ATOMS2=@phi-3
ATOMS3=@phi-4
ATOMS4=@phi-5
ATOMS5=@phi-6
ATOMS6=@phi-7
ATOMS7=@phi-8
LABEL=jhahn
... JCOUPLING
# xxxxWxxxx
JCOUPLING ...
Generated by Doxygen
COUPLING1=-0.49
COUPLING2=-0.54
COUPLING3=-0.53
COUPLING4=-0.39
COUPLING5=-0.39
COUPLING1=6.05
COUPLING2=5.95
COUPLING3=6.44
COUPLING4=6.53
COUPLING5=5.93
COUPLING6=6.98
COUPLING7=7.16
500
Additional Modules
ADDCOUPLINGS
TYPE=CCG
NOPBC
ATOMS1=67,47,49,52 COUPLING1=1.59
LABEL=jccg
... JCOUPLING
# xxxxWxxxx
JCOUPLING ...
ADDCOUPLINGS
TYPE=NCG
NOPBC
ATOMS1=47,49,52,53 COUPLING1=1.21
LABEL=jncg
... JCOUPLING
# Chemical shifts
cs: CS2BACKBONE ATOMS=1-111 NRES=9 DATA=data TEMPLATE=egaawaass.pdb NOPBC
# metainference entries
#RDCS
METAINFERENCE ...
ARG=(nh\.rdc_.*),pb.bias
PARARG=(nh\.exp_.*)
REWEIGHT
NOISETYPE=MGAUSS
OPTSIGMAMEAN=SEM AVERAGING=200
SCALEDATA SCALE_PRIOR=GAUSSIAN SCALE0=8.0 DSCALE=0.5
SIGMA0=5.0 SIGMA_MIN=0.0001 SIGMA_MAX=15.0 DSIGMA=0.1
WRITE_STRIDE=10000
LABEL=byrdcnh
... METAINFERENCE
#RDCS
METAINFERENCE ...
ARG=(caha\.rdc_.*),pb.bias
PARARG=(caha\.exp_.*)
REWEIGHT
NOISETYPE=MGAUSS
OPTSIGMAMEAN=SEM AVERAGING=200
SCALEDATA SCALE_PRIOR=GAUSSIAN SCALE0=9.0 DSCALE=0.5
SIGMA0=5.0 SIGMA_MIN=0.0001 SIGMA_MAX=15.0 DSIGMA=0.1
WRITE_STRIDE=10000
LABEL=byrdccaha
... METAINFERENCE
#JC
METAINFERENCE ...
ARG=(jhan\.j_.*),(jhahn\.j_.*),(jccg\.j.*),(jncg\.j.*),pb.bias
PARARG=(jhan\.exp_.*),(jhahn\.exp_.*),(jccg\.exp.*),(jncg\.exp.*)
REWEIGHT
NOISETYPE=MGAUSS
OPTSIGMAMEAN=SEM AVERAGING=200
SIGMA0=5.0 SIGMA_MIN=0.0001 SIGMA_MAX=15.0 DSIGMA=0.1
WRITE_STRIDE=10000
LABEL=byj
... METAINFERENCE
#CS
METAINFERENCE ...
ARG=(cs\.ca_.*),(cs\.cb_.*),pb.bias
PARARG=(cs\.expca.*),(cs\.expcb.*)
REWEIGHT
NOISETYPE=MOUTLIERS
OPTSIGMAMEAN=SEM AVERAGING=200
SIGMA0=5.0 SIGMA_MIN=0.0001 SIGMA_MAX=15.0 DSIGMA=0.1
WRITE_STRIDE=10000
LABEL=bycs
... METAINFERENCE
# output from METAINFERENCE
Generated by Doxygen
8.1 PLUMED-ISDB
PRINT
PRINT
PRINT
PRINT
ARG=byrdcnh.*
ARG=byrdccaha.*
ARG=byj.*
ARG=bycs.*
501
STRIDE=200
STRIDE=200
STRIDE=200
STRIDE=200
FILE=BAYES.RDC.NH
FILE=BAYES.RDC.CAHA
FILE=BAYES.J
FILE=BAYES.CS
# the following are usefull for the analysis on-the-fly of the quality of the agreement with the experimentl d
ENSEMBLE ...
ARG=(nh\.rdc_.*),(caha\.rdc_.*),(jhan\.j_.*),(jhahn\.j_.*),(jccg\.j_.*),(jncg\.j_.*),(cs\..._.*),pb.bias R
LABEL=ens
... ENSEMBLE
STATS ...
ARG=(ens\.nh\.rdc_.*) PARARG=(nh\.exp_.*)
LABEL=nhst
... STATS
STATS ...
ARG=(ens\.caha\.rdc_.*) PARARG=(caha\.exp_.*)
LABEL=cahast
... STATS
STATS ...
ARG=(ens\.cs\..._.*) PARARG=(cs\.exp.*)
LABEL=csst
... STATS
STATS ...
ARG=(ens\.jhan\.j_.*) PARARG=(jhan\.exp_.*)
LABEL=jhanst
... STATS
STATS ...
ARG=(ens\.jhahn\.j_.*) PARARG=(jhahn\.exp_.*)
LABEL=jhahnst
... STATS
STATS ...
ARG=(ens\.jccg\.j.*),(ens\.jccg\.j.*) PARARG=(jccg\.exp_.*),(jccg\.exp_.*)
SQDEVSUM
LABEL=jw5ccyst
... STATS
STATS ...
ARG=(ens\.jncg\.j.*),(ens\.jncg\.j.*) PARARG=(jncg\.exp_.*),(jncg\.exp_.*)
SQDEVSUM
LABEL=jw5ncyst
... STATS
#output from STATS
PRINT ARG=nhst.*
STRIDE=2000 FILE=ST.RDC.NH
PRINT ARG=cahast.*
STRIDE=2000 FILE=ST.RDC.CAHA
PRINT ARG=csst.*
STRIDE=2000 FILE=ST.CS
PRINT ARG=jhanst.*,jhahnst.*,jw5ccyst.*,jw5ncyst.* STRIDE=2000 FILE=ST.J
As for the former case we are running a multiple-replica simulation where in addition to multiple-walker metadynamics we are also coupling the replicas through Metainference. The use of multiple-walkers metadynamics is here key
in order to have the same bias defined for all the replicas. This allows us to calculate a weighted average of the
experimental observables where the weights are defined univocally from the bias [79] .
mpiexec -np 14 gmx_mpi mdrun -s topolnew -multi 14 -plumed plumed-eef1-pbmetad-m_m.dat -table table.xvg -table
8.1.5.2
ISDB: setting up a SAXS post processing and refinement calculation using MARTINI form factors
Authors
Cristina Paissoni
Generated by Doxygen
502
Additional Modules
8.1.5.2.1
Aims
This tutorial is thought to illustrate how it is possible to compute SAXS intensities from single PDB files or trajectories using PLUMED. In particular, we will show how to compute scattering intensities with the hybrid coarsegrained/atomistic approach that is described in [82] . The tutorial will provide basic instructions to prepare files for
the back-calculation of SAXS intensities using the hybrid approach (this process is simplified by the possibility to
use an ad-hoc python script). Further, it is explained how to adjust the plumed input file for specific purposes, e.g.
to use SAXS data as restraints in MD simulations or to compare SAXS intensities computed with both the atomistic
and the hybrid approach.
8.1.5.2.2
Objectives
Once this tutorial is completed users will be able to:
• Calculate SAXS intensities using PLUMED from PDB files or trajectories.
• Setup a Metainference simulations using SAXS intensities as restraints (to this aim, ISDB: setting up a Metadynamics Metainfere
is required as a prior condition)
8.1.5.2.3
Resources
TheTARBALL for this project contains the following files:
• martiniFormFactor_p2.py and martiniFormFactor_p3.py: two helpful python scripts to be used with python 2 or
python 3, respectively. These are based on the martinize.py script (http://cgmartini.nl/index.←php/tools2/proteins-and-bilayers/204-martinize)
• start.pdb and samplextc.xtc: PDB and trajectory files on which you can perform the calculations;
• SASDAB7.dat: a file containing SAXS intensities, downloaded from the SASDB database [83] .
This tutorial has been tested on PLUMED version 2.5.1
8.1.5.2.4
Introduction
Calculations of Small-angle X-ray scattering (SAXS) intensities from a structure of N atoms could be extremely
demanding from a computational perspective as it is an O(N 2 ) problem. This issue has limited the applicability
of SAXS in numerous situations, including their use as restraints in combination with MD simulations. A strategy
to reduce the cost of computing SAXS from atomic structure consists in using a coarse grain representation of
the structure, represented as a collection of M beads with M 0 at any X(t), resulting in enhanced barrier-crossing.
(The value of Hlog is automatically set according to FLOG).
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
TEMP
Temperature of the fictitious dynamical variables in LogMFD/PD thermostat. If
not provided or provided as 0, it will be taken from the temperature of the MD
system.
TAMD
When TAMD=1, TAMD/d-AFED calculations can be performed instead of
LogMFD. Otherwise, the LogMFD protocol is switched on (default).
ALPHA
Alpha parameter for LogMFD. If not provided or provided as 0, it will be taken as
1/gamma. If gamma is also not provided, Alpha is set as 4, which is a sensible
value when the unit of kcal/mol is used.
Gamma parameter for LogMFD. If not provided or provided as 0, it will be taken
as 1/alpha. If alpha is also not provided, Gamma is set as 0.25, which is a
sensible value when the unit of kcal/mol is used.
The initial values of the fictitious dynamical variables. If not provided, they are
set equal to their corresponding CVs for the initial atomic configuration.
GAMMA
FICT
VFICT
MFICT
XETA
The initial velocities of the fictitious dynamical variables. If not provided, they
will be taken as 0.
Masses of each fictitious dynamical variable. If not provided, they will be taken
as 10000.
The initial eta variable of the Nose-Hoover thermostat for the fictitious dynamical variables. If not provided, it will be taken as 0.
VETA
The initial velocity of eta variable. If not provided, it will be taken as 0.
META
Mass of eta variable. If not provided, it will be taken as N ∗ kb ∗ T ∗ 100 ∗ 100.
WORK
The initial value of the work done by fictitious dynamical variables in each
replica. If not provided, it will be taken as 0.
Generated by Doxygen
512
Additional Modules
Examples
8.2.1.1.4
Examples
8.2.1.1.4.1
Example of LogMFD
The following input file tells plumed to restrain collective variables to the fictitious dynamical variables in LogMFD/PD.
plumed.dat
BEGIN_PLUMED_FILE
UNITS TIME=fs LENGTH=1.0 ENERGY=kcal/mol Mass=1.0 CHARGE=1.0
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
# LogMFD
LOGMFD ...
LABEL=logmfd
ARG=phi,psi
KAPPA=100.0,100.0
DELTA_T=0.5
INTERVAL=500
TEMP=300.0
FLOG=5.0
MFICT=5000000.0,5000000.0
# FICT=0.8,0.8
VFICT=3.5e-4,3.5e-4
ALPHA=4.0
THERMOSTAT=NVE
VETA=0.0
META=20000.0
FICT_MAX=3.1,3.1
FICT_MIN=-3.1,-3.1
... LOGMFD
To submit this simulation with Gromacs, use the following command line to execute a LogMFD run with GromacsMD. Here TOPO/topol0.tpr is an input file which contains atomic coordinates and Gromacs parameters.
BEGIN_PLUMED_FILE
gmx_mpi mdrun -s TOPO/topol0.tpr -plumed
This command will output files named logmfd.out and replica.out.
The output file logmfd.out records free energy and all fictitious dynamical variables at every MFD step.
logmfd.out
BEGIN_PLUMED_FILE
# LogMFD
# CVs : phi psi
# Mass for CV particles : 5000000.000000000 5000000.000000000
# Mass for thermostat
:
20000.000000000
# 1:iter_md, 2:Flog, 3:2*Ekin/gkb[K], 4:eta, 5:Veta,
# 6:phi_fict(t), 7:phi_vfict(t), 8:phi_force(t),
# 9:psi_fict(t), 10:psi_vfict(t), 11:psi_force(t),
1
4.99918574
308.24149708
0.00000000
2
4.99836196
308.26124159
0.00000000
3
4.99743572
308.28344595
0.00000000
...
0.00000000
0.00000000
0.00000000
-2.85605938
-2.85588436
-2.85570932
Generated by Doxygen
0.00035002
0.00035005
0.00035007
8.2 Logarithmic Mean Force Dynamics
513
The output file replica.out records all collective variables at every MFD step.
replica.out
BEGIN_PLUMED_FILE
# Replica No. 0 of 1.
# 1:iter_md, 2:work, 3:weight,
# 4:phi(q)
# 5:psi(q)
1
-8.142952e-04
1.000000e+00
2
-1.638105e-03
1.000000e+00
3
-2.564398e-03
1.000000e+00
...
8.2.1.1.4.2
-2.80432694
-2.80893462
-2.80244854
2.78661234
2.79211039
2.79182665
Example of LogPD
Use the following command line to execute a LogPD run using two MD replicas (note that only Gromacs is currently
available for LogPD). Here TOPO/topol0.tpr and TOPO/topol1.tpr are input files which contain atomic coordinates
of each replica and Gromacs parameters.
BEGIN_PLUMED_FILE
mpirun -np 2 gmx_mpi mdrun -s TOPO/topol -plumed -multi 2
This command will output files named logmfd.out, replica.out.0 and replica.out.1.
The output file logmfd.out records free energy and all fictitious dynamical variables at every MFD step.
logmfd.out
BEGIN_PLUMED_FILE
# LogPD, replica parallel of LogMFD
# number of replica : 2
# CVs : phi psi
# Mass for CV particles : 5000000.000000000 5000000.000000000
# Mass for thermostat
:
20000.000000000
# 1:iter_md, 2:Flog, 3:2*Ekin/gkb[K], 4:eta, 5:Veta,
# 6:phi_fict(t), 7:phi_vfict(t), 8:phi_force(t),
# 9:psi_fict(t), 10:psi_vfict(t), 11:psi_force(t),
1
5.00224715
308.16814691
0.00000000
2
5.00476934
308.10774854
0.00000000
3
5.00702463
308.05376594
0.00000000
...
0.00000000
0.00000000
0.00000000
The output file replica.out.0 records all collective variables of replica No.0 at every MFD step.
replica.out.0
BEGIN_PLUMED_FILE
# Replica No. 0 of 2.
# 1:iter_md, 2:work, 3:weight,
# 4:phi(q)
# 5:psi(q)
1
1.843110e-03
5.003389e-01
2
3.466179e-03
5.010942e-01
3
4.927870e-03
5.017619e-01
...
-1.10929125
-1.05020764
-1.04968867
0.83348865
0.78731283
0.79635198
The output file replica.out.1 records all collective variables of replica No.1 at every MFD step.
replica.out.1
BEGIN_PLUMED_FILE
# Replica No. 1 of 2.
# 1:iter_md, 2:work, 3:weight,
# 4:phi(q)
# 5:psi(q)
1
2.651173e-03
4.996611e-01
2
6.075530e-03
4.989058e-01
3
9.129358e-03
4.982381e-01
...
Generated by Doxygen
-1.06802968
-1.09264741
-1.08517238
0.74605205
0.72681448
0.74084241
-0.95937173
-0.95919679
-0.95902187
0.00034994
0.00034989
0.00034983
514
Additional Modules
8.3
MAZE
maze is a module for PLUMED2, which implements enhanced sampling methods for ligand unbinding from protein
tunnels. The maze module is developed and maintained by Jakub Rydzewski at the Institute of Physics,
Nicolaus Copernicus University, Toruń, Poland. See this link for additional information.
The maze module is an optional module for PLUMED2 that needes to be enabled when configuring the compilation
of PLUMED2. You can either pass a flag '--enable-modules=maze' or a '--enable-modules=all' when running the
configure script.
See the following sections for further information:
• Loss
• Optimizers
• Biases
8.3.1
Loss
The following list contains the loss functions available in the maze module.
MAZE_LOSS
8.3.1.1
MAZE_LOSS
This is part of the maze module
It is only available if you configure PLUMED with ./configure –enable-modules=maze . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Define a coarse-grained loss function describing interactions in a ligand-protein complex, which is minimized during
the simulation to obtain ligand unbinding pathways.
The loss function is the following:
L=
Np
X
−γ
ri−α e−βri ,
i=1
where Np is the number of ligand-protein atom pairs, r is a rescaled distance between the ith pair, and α, β, γ are
the positive parameters defined in that order by the PARAMS keyword.
Compulsory keywords
PARAMS
Parameters for the loss function.
Options
Generated by Doxygen
8.3 MAZE
515
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
Examples
The loss function can be defined in the following way:
BEGIN_PLUMED_FILE
l: MAZE_LOSS PARAMS=1,1,1
8.3.2
Optimizers
The following list contains the optimizers available in the maze module.
MAZE_MEMETIC_SAMPLING
MAZE_RANDOM_ACCELERATION_MD
MAZE_RANDOM_WALK
MAZE_SIMULATED_ANNEALING
MAZE_STEERED_MD
8.3.2.1
MAZE_MEMETIC_SAMPLING
This is part of the maze module
It is only available if you configure PLUMED with ./configure –enable-modules=maze . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Calculates the biasing direction along which the ligand unbinds by minimizing the MAZE_LOSS function. The
optimal biasing direction is determined by performing a population-based memetic search with local heuristics.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
x
Optimal biasing direction; x component.
y
Optimal biasing direction; y component.
z
Optimal biasing direction; z component.
loss
Loss function value defined by the provided pairing function.
sr
Sampling radius. Reduces sampling to the local proximity of the ligand position.
Generated by Doxygen
516
Additional Modules
The atoms involved can be specified using
LIGAND
Indices of ligand atoms..
Groups and Virtual Atoms
For more information on how to specify lists of atoms see
PROTEIN
Indices of protein atoms..
Groups and Virtual Atoms
For more information on how to specify lists of atoms see
Compulsory keywords
N_ITER
OPTIMIZER_STRIDE
Number of optimization steps. Required only for optimizers, do not pass this keyword
to the fake optimizers (results in crash) , e.g., random walk, steered MD, or random
acceleration MD.
Optimizer stride. Sets up a callback function that launches the optimization process
every OPTIMIZER_STRIDE.
CAPACITY
Sampling set size.
MUTATION_RATE
Probability of mutation.
MATING_RATE
Probability of mating.
CAUCHY_ALPHA
Mean of cauchy distribution for sampling.
CAUCHY_BETA
Spread of cauchy distribution for sampling.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Perform the simulation in serial – used only for debugging purposes, should not be used otherwise.
SERIAL
PAIR
( default=off ) Pair only the 1st element of the 1st group with the 1st element in
the second, etc.
NLIST
( default=on ) Use a neighbor list of ligand-protein atom pairs to speed up the
calculating of the distances.
LOCAL_SEARCH_ON
( default=off ) Turn local search on.
NL_CUTOFF
Neighbor list cut-off for the distances of ligand-protein atom pairs.
NL_STRIDE
Update stride for the ligand-protein atom pairs in the neighbor list.
LOSS
Loss function describing ligand-protein interactions required by every optimizer.
N_LOCAL_ITER
LOCAL_SEARCH_RATE
LOCAL_SEARCH_TYPE
Number of local search iterations.
Rate of mutation in local search.
Type of local search.
Examples
Every optimizer implemented in the maze module needs a loss function as an argument, and it should be passed
using the MAZE_LOSS keyword.
Generated by Doxygen
8.3 MAZE
517
BEGIN_PLUMED_FILE
MAZE_MEMETIC_SAMPLING ...
LABEL=ma
LOSS=l
N_ITER=10
OPTIMIZER_STRIDE=200
CAPACITY=20
LOCAL_SEARCH_ON
N_LOCAL_ITER=10
LOCAL_SEARCH_RATE=0.1
LOCAL_SEARCH_TYPE=stochastic_hill_climbing
MUTATION_RATE=0.1
MATING_RATE=0.7
CAUCHY_ALPHA=0
CAUCHY_BETA=0.1
LIGAND=2635-2646
PROTEIN=1-2634
... MAZE_MEMETIC_SAMPLING
As shown above, each optimizer should be provided with the LIGAND and the PROTEIN keywords.
The neighbor list can be turned on by providing the NLIST keyword.
8.3.2.2
MAZE_RANDOM_ACCELERATION_MD
This is part of the maze module
It is only available if you configure PLUMED with ./configure –enable-modules=maze . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Performs random acceleratiob MD within the protein matrix.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
x
Optimal biasing direction; x component.
y
Optimal biasing direction; y component.
z
Optimal biasing direction; z component.
loss
Loss function value defined by the provided pairing function.
sr
Sampling radius. Reduces sampling to the local proximity of the ligand position.
dist
Distance traveled in one sampling interval.
tdist
Total distance traveled by biased atoms.
The atoms involved can be specified using
Generated by Doxygen
518
Additional Modules
LIGAND
Indices of ligand atoms..
Groups and Virtual Atoms
For more information on how to specify lists of atoms see
PROTEIN
Indices of protein atoms..
Groups and Virtual Atoms
For more information on how to specify lists of atoms see
Compulsory keywords
OPTIMIZER_STRIDE
Optimizer stride. Sets up a callback function that launches the optimization process
every OPTIMIZER_STRIDE.
R_MIN
Minimal distance traveled before sampling a new direction of biasing.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Perform the simulation in serial – used only for debugging purposes, should not be used otherwise.
SERIAL
PAIR
( default=off ) Pair only the 1st element of the 1st group with the 1st element in
the second, etc.
NLIST
( default=on ) Use a neighbor list of ligand-protein atom pairs to speed up the
calculating of the distances.
NL_CUTOFF
Neighbor list cut-off for the distances of ligand-protein atom pairs.
NL_STRIDE
Update stride for the ligand-protein atom pairs in the neighbor list.
LOSS
Loss function describing ligand-protein interactions required by every optimizer.
Examples
Every optimizer implemented in the maze module needs a loss function as an argument, and it should be passed
using the MAZE_LOSS keyword.
BEGIN_PLUMED_FILE
MAZE_RANDOM_ACCELERATION_MD ...
LABEL=rw
OPTIMIZER_STRIDE=_
LOSS=l
RMIN=_
LIGAND=2635-2646
PROTEIN=1-2634
... MAZE_RANDOM_ACCELERATION_MD
As shown above, each optimizer should be provided with the LIGAND and the PROTEIN keywords.
8.3.2.3
MAZE_RANDOM_WALK
Generated by Doxygen
8.3 MAZE
519
This is part of the maze module
It is only available if you configure PLUMED with ./configure –enable-modules=maze . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Fake optimizer that can be used for debugging.
This is dummy optimizer that can be used for debugging and monitoring purposes. It returns a random direction of
biasing, changed every OPTIMIZER_STRIDE.
Performs a random walk within the protein matrix.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
x
Optimal biasing direction; x component.
y
Optimal biasing direction; y component.
z
Optimal biasing direction; z component.
loss
Loss function value defined by the provided pairing function.
sr
Sampling radius. Reduces sampling to the local proximity of the ligand position.
The atoms involved can be specified using
LIGAND
Indices of ligand atoms..
Groups and Virtual Atoms
For more information on how to specify lists of atoms see
PROTEIN
Indices of protein atoms..
Groups and Virtual Atoms
For more information on how to specify lists of atoms see
Compulsory keywords
OPTIMIZER_STRIDE
Optimizer stride. Sets up a callback function that launches the optimization process
every OPTIMIZER_STRIDE.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Perform the simulation in serial – used only for debugging purposes, should not be used otherwise.
SERIAL
Generated by Doxygen
520
Additional Modules
PAIR
( default=off ) Pair only the 1st element of the 1st group with the 1st element in
the second, etc.
NLIST
( default=on ) Use a neighbor list of ligand-protein atom pairs to speed up the
calculating of the distances.
NL_CUTOFF
Neighbor list cut-off for the distances of ligand-protein atom pairs.
NL_STRIDE
Update stride for the ligand-protein atom pairs in the neighbor list.
LOSS
Loss function describing ligand-protein interactions required by every optimizer.
Examples
Every optimizer implemented in the maze module needs a loss function as an argument, and it should be passed
using the MAZE_LOSS keyword.
BEGIN_PLUMED_FILE
MAZE_RANDOM_WALK ...
LABEL=rw
LOSS=l
OPTIMIZER_STRIDE=200
LIGAND=2635-2646
PROTEIN=1-2634
... MAZE_RANDOM_WALK
As shown above, each optimizer should be provided with the LIGAND and the PROTEIN keywords.
8.3.2.4
MAZE_SIMULATED_ANNEALING
This is part of the maze module
It is only available if you configure PLUMED with ./configure –enable-modules=maze . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Calculates the biasing direction along which the ligand unbinds by minimizing the MAZE_LOSS function. The
optimal biasing direction is determined by performing simulated annealing.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
x
Optimal biasing direction; x component.
y
Optimal biasing direction; y component.
z
Optimal biasing direction; z component.
loss
Loss function value defined by the provided pairing function.
sr
Sampling radius. Reduces sampling to the local proximity of the ligand position.
Generated by Doxygen
8.3 MAZE
521
The atoms involved can be specified using
LIGAND
Indices of ligand atoms..
Groups and Virtual Atoms
For more information on how to specify lists of atoms see
PROTEIN
Indices of protein atoms..
Groups and Virtual Atoms
For more information on how to specify lists of atoms see
Compulsory keywords
N_ITER
Number of optimization steps. Required only for optimizers, do not pass this
keyword to the fake optimizers (results in crash) , e.g., random walk, steered
MD, or random acceleration MD.
OPTIMIZER_STRIDE
Optimizer stride. Sets up a callback function that launches the optimization
process every OPTIMIZER_STRIDE.
PROBABILITY_DECREASER
Temperature-like parameter that is decreased during optimization to modify
the Metropolis-Hastings acceptance probability.
COOLING
Reduction factor for PROBABILITY_DECREASER, should be in (0, 1].
COOLING_SCHEME
Cooling scheme: geometric.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Perform the simulation in serial – used only for debugging purposes, should not be used otherwise.
SERIAL
PAIR
( default=off ) Pair only the 1st element of the 1st group with the 1st element in
the second, etc.
NLIST
( default=on ) Use a neighbor list of ligand-protein atom pairs to speed up the
calculating of the distances.
NL_CUTOFF
Neighbor list cut-off for the distances of ligand-protein atom pairs.
NL_STRIDE
Update stride for the ligand-protein atom pairs in the neighbor list.
LOSS
Loss function describing ligand-protein interactions required by every optimizer.
Examples
Every optimizer implemented in the maze module needs a loss function as an argument, and it should be passed
using the MAZE_LOSS keyword.
In the following example simulated annealing is launched for 1000 iterations as the optimizer for the loss function
every 200 ps. The geometric cooling scheme is used.
BEGIN_PLUMED_FILE
UNITS LENGTH=A TIME=ps ENERGY=kcal/mol
Generated by Doxygen
522
Additional Modules
MAZE_SIMULATED_ANNEALING ...
LABEL=sa
LOSS=l
N_ITER=1000
OPTIMIZER_STRIDE=200
PROBABILITY_DECREASER=300
COOLING=0.95
COOLING_TYPE=geometric
LIGAND=2635-2646
PROTEIN=1-2634
... MAZE_SIMULATED_ANNEALING
As shown above, each optimizer should be provided with the LIGAND and the PROTEIN keywords.
8.3.2.5
MAZE_STEERED_MD
This is part of the maze module
It is only available if you configure PLUMED with ./configure –enable-modules=maze . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Performs a linear unbinding along a predefined biasing direction that needs to be provided using the PULLING
keyword.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
x
Optimal biasing direction; x component.
y
Optimal biasing direction; y component.
z
Optimal biasing direction; z component.
loss
Loss function value defined by the provided pairing function.
sr
Sampling radius. Reduces sampling to the local proximity of the ligand position.
tdist
Total distance traveled by biased atoms.
The atoms involved can be specified using
LIGAND
Indices of ligand atoms..
Groups and Virtual Atoms
For more information on how to specify lists of atoms see
PROTEIN
Indices of protein atoms..
Groups and Virtual Atoms
For more information on how to specify lists of atoms see
Generated by Doxygen
8.3 MAZE
523
Compulsory keywords
OPTIMIZER_STRIDE
Optimizer stride. Sets up a callback function that launches the optimization process
every OPTIMIZER_STRIDE.
PULLING
Constant biasing direction.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Perform the simulation in serial – used only for debugging purposes, should not be used otherwise.
SERIAL
PAIR
( default=off ) Pair only the 1st element of the 1st group with the 1st element in
the second, etc.
NLIST
( default=on ) Use a neighbor list of ligand-protein atom pairs to speed up the
calculating of the distances.
NL_CUTOFF
Neighbor list cut-off for the distances of ligand-protein atom pairs.
NL_STRIDE
Update stride for the ligand-protein atom pairs in the neighbor list.
LOSS
Loss function describing ligand-protein interactions required by every optimizer.
Examples
Every optimizer implemented in the maze module needs a loss function as an argument, and it should be passed
using the MAZE_LOSS keyword.
BEGIN_PLUMED_FILE
MAZE_STEERED_MD ...
LABEL=smd
LOSS=l
PULLING=0.3,0.3,0.3
OPTIMIZER_STRIDE=_
LIGAND=2635-2646
PROTEIN=1-2634
... MAZE_STEERED_MD
As shown above, each optimizer should be provided with the LIGAND and the PROTEIN keywords.
8.3.3
Biases
The following list contains the biases available in the maze module.
MAZE_OPTIMIZER_BIAS
Generated by Doxygen
524
Additional Modules
8.3.3.1
MAZE_OPTIMIZER_BIAS
This is part of the maze module
It is only available if you configure PLUMED with ./configure –enable-modules=maze . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Biases the ligand along the direction calculated by the chosen MAZE_OPTIMIZER.
OptimizerBias is a class deriving from Bias, and it is used to adaptively bias a ligand-protein system toward an
optimal solution found by the chosen optimizer.
Remember to define the loss function (MAZE_LOSS) and the optimizer (MAZE_OPTIMIZER) prior to the adaptive
bias for the optimizer.
The adaptive bias potential is the following:
2
x∗t − xt
∗
,
V (xt ) = α wt − (x − xt−τ ) · ∗
kxt − xt k
where x∗t is the optimal solution at time t, w is the biasing rate, τ is the interval at which the loss function is
minimized, and α is a scaled force constant.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
force2
Square of the biasing force.
x
Optimal biasing direction: x component.
y
Optimal biasing direction: y component.
z
Optimal biasing direction: z component.
tdist
Total distance traveled by biased atoms.
Compulsory keywords
BIASING_RATE
Biasing rate.
ALPHA
OPTIMIZER
Rescaled force constant.
Optimization technique to minimize the collective variable for ligand unbinding: RANDOM_←WALK, STEERED_MD, RANDOM_ACCELERATION_MD, SIMULATED_ANNEALING, M←EMETIC_SAMPLING
Options
Generated by Doxygen
8.4 Experiment Directed Simulation
525
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
Examples
In the following example the bias potential biases a ligand atom (which have to be given as an argument) with the
biasing rate equal to 0.02 A/ps, and the biasing constant equal to 3.6 kcal/(mol A). It also takes an optimizer (see
MAZE_OPTIMIZER).
BEGIN_PLUMED_FILE
UNITS LENGTH=A TIME=ps ENERGY=kcal/mol
p: POSITION ATOM=2635 NOPBC
MAZE_OPTIMIZER_BIAS ...
LABEL=bias
ARG=p.x,p.y,p.z
BIASING_RATE=0.02
ALPHA=3.6
OPTIMIZER=opt
... MAZE_OPTIMIZER_BIAS
8.4
Experiment Directed Simulation
Overview
This Experiment Directed Simulation module contains methods for adaptively determining linear bias parameters
such that each biased CV samples a new target mean value. This module implements the stochastic gradient
descent algorithm in the original EDS paper [26] as well as additional minimization algorithms for Coarse-Grained
Directed Simulation [65]. There is a recent review on the method and its applications here: [66].
Notice that a similar method is available as MAXENT, although with different features and using a different optimization algorithm.
Generated by Doxygen
526
Additional Modules
Installation
This module is not installed by default. Add '--enable-modules=eds' to your './configure' command when building
PLUMED to enable these features.
Usage
Currently, all features of the EDS module are included in a single EDS bias function: EDS
A tutorial using EDS specifically for biasing coordination number can be found on Andrew White's webpage.
Module Contents
• Biases Documentation
8.4.1
Biases Documentation
The following list contains descriptions of biases developed for the PLUMED-EDS module. They can be used in
combination with other biases outside of the EDS module.
EDS
8.4.1.1
Add a linear bias on a set of observables.
EDS
This is part of the eds module
It is only available if you configure PLUMED with ./configure –enable-modules=eds . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Add a linear bias on a set of observables.
This force is the same as the linear part of the bias in RESTRAINT, but this bias has the ability to compute the
prefactors adaptively using the scheme of White and Voth [26] in order to match target observable values for a set
of CVs. Further updates to the algorithm are described in [65] and you can read a review on the method and its
applications here: [66].
You can see a tutorial on EDS specifically for biasing coordination number at Andrew White's webpage.
The addition to the potential is of the form
X αi
i
si
xi
where for CV xi , a coupling constant αi is determined adaptively or set by the user to match a target value for xi .
si is a scale parameter, which by default is set to the target value. It may also be set separately.
Generated by Doxygen
8.4 Experiment Directed Simulation
527
Warning
It is not possible to set the target value of the observable to zero with the default value of si as this will cause
a divide-by-zero error. Instead, set si = 1 or modify the CV so the desired target value is no longer zero.
Notice that a similar method is available as MAXENT, although with different features and using a different optimization algorithm.
Virial
The bias forces modify the virial and this can change your simulation density if the bias is used in an NPT simulation.
One way to avoid changing the virial contribution from the bias is to add the keyword VIRIAL=1.0, which changes
how the bias is computed to minimize its contribution to the virial. This can also lead to smaller magnitude biases
that are more robust if transferred to other systems. VIRIAL=1.0 can be a reasonable starting point and increasing
the value changes the balance between matching the set-points and minimizing the virial. See [66] for details on
the equations. Since the coupling constants are unique with a single CV, VIRIAL is not applicable with a single CV.
When used with multiple CVs, the CVs should be correlated which is almost always the case.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
force2
squared value of force from the bias
pressure
If using virial keyword, this is the curent sum of virials. It is in units of pressure (energy / vol∧ 3)
_coupling
For each named CV biased, there will be a corresponding output CV_coupling storing the current
linear bias prefactor.
Compulsory keywords
RANGE
( default=25.0 ) The (starting) maximum increase in coupling constant per PERIOD (in kB T /[BIAS←_SCALE unit]) for each CV based
SEED
( default=0 ) Seed for random order of changing bias
INIT
( default=0 ) Starting value for coupling constant
FIXED
( default=0 ) Fixed target values for coupling constant. Non-adaptive.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
LM
( default=off ) Use Levenberg-Marquadt algorithm along with simultaneous keyword. Otherwise use gradient descent.
Generated by Doxygen
528
LM_MIXING
RAMP
Additional Modules
( default=on ) Initial mixing parameter when using Levenberg-Marquadt minimization.
( default=off ) Slowly increase bias constant to a fixed value
COVAR
( default=off ) Utilize the covariance matrix when updating the bias. Default Off,
but may be enabled due to other options
FREEZE
( default=off ) Fix bias at current level (only used for restarting).
MEAN
( default=off ) Instead of using final bias level from restart, use average. Can
only be used in conjunction with FREEZE
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
CENTER
The desired centers (equilibrium values) which will be sought during the adaptive linear biasing. This is for fixed centers
CENTER_ARG
The desired centers (equilibrium values) which will be sought during the adaptive linear biasing. CENTER_ARG is for calculated centers, e.g. from a CV or
analysis.
PERIOD
Steps over which to adjust bias for adaptive or ramping
BIAS_SCALE
A divisor to set the units of the bias. If not set, this will be the CENTER value
by default (as is done in White and Voth 2014).
TEMP
The system temperature. If not provided will be taken from MD code (if available)
MULTI_PROP
What proportion of dimensions to update at each step. Must be in interval
[1,0), where 1 indicates all and any other indicates a stochastic update. If not
set, default is 1 / N, where N is the number of CVs.
VIRIAL
Add an update penalty for having non-zero virial contributions. Only makes
sense with multiple correlated CVs.
RESTART_FMT
the format that should be used to output real numbers in EDS restarts
OUT_RESTART
Output file for all information needed to continue EDS simulation. If you have
the RESTART directive set (global or for EDS), this file will be appended to.
Note that the header will be printed again if appending.
IN_RESTART
Read this file to continue an EDS simulation. If same as OUT_RESTART and
you have not set the RESTART directive, the file will be backed-up and overwritten with new output. If you do have the RESTART flag set and it is the same
name as OUT_RESTART, this file will be appended.
RESTART
allows per-action setting of restart (YES/NO/AUTO)
Examples
The following input for a harmonic oscillator of two beads will adaptively find a linear bias to change the mean and
variance to the target values. The PRINT line shows how to access the value of the coupling constants.
Generated by Doxygen
8.5 Extended-System Adaptive Biasing Force
529
BEGIN_PLUMED_FILE
dist: DISTANCE ATOMS=1,2
# this is the squared of the distance
dist2: COMBINE ARG=dist POWERS=2 PERIODIC=NO
#bias mean and variance
eds: EDS ARG=dist,dist2 CENTER=2.0,1.0 PERIOD=50000 TEMP=1.0
PRINT ARG=dist,dist2,eds.dist_coupling,eds.dist2_coupling,eds.bias,eds.force2 FILE=colvars.dat STRIDE=100
Rather than trying to find the coupling constants adaptively, one can ramp up to a constant value.
BEGIN_PLUMED_FILE
#ramp couplings from 0,0 to -1,1 over 50000 steps
eds: EDS ARG=dist,dist2 CENTER=2.0,1.0 FIXED=-1,1 RAMP PERIOD=50000 TEMP=1.0
#same as above, except starting at -0.5,0.5 rather than default of 0,0
eds: EDS ARG=dist,dist2 CENTER=2.0,1.0 FIXED=-1,1 INIT=-0.5,0.5 RAMP PERIOD=50000 TEMP=1.0
A restart file can be added to dump information needed to restart/continue simulation using these parameters every
PERIOD.
BEGIN_PLUMED_FILE
#add the option to write to a restart file
eds: EDS ARG=dist,dist2 CENTER=2.0,1.0 PERIOD=50000 TEMP=1.0 OUT_RESTART=restart.dat
Read in a previous restart file. Adding RESTART flag makes output append
BEGIN_PLUMED_FILE
eds: EDS ARG=dist,dist2 CENTER=2.0,1.0 PERIOD=50000 TEMP=1.0 IN_RESTART=restart.dat RESTART
Read in a previous restart file and freeze the bias at the final level from the previous simulation
BEGIN_PLUMED_FILE
eds: EDS ARG=dist,dist2 CENTER=2.0,1.0 TEMP=1.0 IN_RESTART=restart.dat FREEZE
Read in a previous restart file and freeze the bias at the mean from the previous simulation
BEGIN_PLUMED_FILE
eds: EDS ARG=dist,dist2 CENTER=2.0,1.0 TEMP=1.0 IN_RESTART=restart.dat FREEZE MEAN
Read in a previous restart file and continue the bias, but use the mean from the previous run as the starting point
BEGIN_PLUMED_FILE
eds: EDS ARG=dist,dist2 CENTER=2.0,1.0 PERIOD=50000 TEMP=1.0 IN_RESTART=restart.dat MEAN
8.5
Extended-System Adaptive Biasing Force
Overview
This module contains the eABF/DRR method to do free energy calculation or enhance sampling along CVs.
Generated by Doxygen
530
Additional Modules
Installation
This module is not installed by default. Add '--enable-modules=drr --enable-boost_serialization' to your './configure'
command when building PLUMED to enable these features.
Usage
Please read drr_tool and DRR for more information.
Module Contents
• Biases Documentation
• Command Line Tools
8.5.1
Biases Documentation
The following list contains descriptions of biases developed for the eABF module. They can be used in combination
with other biases outside of the eABF module.
DRR
8.5.1.1
Used to performed extended-system adaptive biasing force(eABF) [36] method on one or more collective
variables. This method is also called dynamic reference restraining(DRR) [37] .
DRR
This is part of the drr module
It is only available if you configure PLUMED with ./configure –enable-modules=drr . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Used to performed extended-system adaptive biasing force(eABF) [36] method on one or more collective variables.
This method is also called dynamic reference restraining(DRR) [37] .
For each collective variable ξi , a fictitious variable λi is attached through a spring. The fictitious variable λi undergoes overdamped Langevin dynamics just like EXTENDED_LAGRANGIAN. The ABF algorithm applies bias force
on λi . The bias force acts on λi is the negative average spring force on λi , which enhances the sampling of λi .
Fbias (λi ) = k(λi − hξi iλi )
If spring force constant k is large enough, then ξi synchronizes with λi . The naive(ABF) estimator is just the negative
average spring force of λi .
The naive(ABF) estimator is biased. There are unbiased estimators such as CZAR(Corrected z-averaged restraint)
[67] and UI(Umbrella Integration). The CZAR estimates the gradients as:
∂A
1 ∂ ln ρ̃ (ξ)
(ξ) = −
+ k (hλi iξ − ξi )
∂ξi
β ∂ξi
Generated by Doxygen
8.5 Extended-System Adaptive Biasing Force
531
The UI estimates the gradients as:
P
A0 (ξ ∗ ) =
i
h ∗
ξ −hξiλ
∗
∗
−
k(ξ
−
λ)
N
(ξ
,
λ)
2
λ
βσλ
P
N
(ξ ∗ , λ)
λ
The code performing UI(colvar_UIestimator.h) is contributed by Haohao Fu [68] . It may be slow. I only change the
Boltzmann constant and output precision in it. For new version and issues, please see: https://github.←-
com/fhh2626/colvars
After running eABF/DRR, the drr_tool utility can be used to extract the gradients and counts files from
.drrstate.
Naive(ABF) estimator's result is in .abf.grad and .abf.count files and CZAR estimator's result is in .czar.grad and .czar.count files.
To get PMF, the abf_integrate(https://github.com/←Colvars/colvars/tree/master/colvartools) is useful.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
_fict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These
quantities will named with the arguments of the bias followed by the character string _tilde. It is
possible to add forces on these variable.
_vfict
one or multiple instances of this quantity can be referenced elsewhere in the input file. These
quantities will named with the arguments of the bias followed by the character string _tilde. It is
NOT possible to add forces on these variable.
_biasforce
The bias force from eABF/DRR of the fictitious particle.
_springforce
Spring force between real CVs and extended CVs
_fictNoPBC
the positions of fictitious particles (without PBC).
Compulsory keywords
TAU
FRICTION
( default=0.5 ) specifies relaxation time on each of variables are, similar to extendedTime←Constant in Colvars
( default=8.0 ) add a friction to the variable, similar to extendedLangevinDamping in Colvars
GRID_MIN
the lower bounds for the grid (GRID_BIN or GRID_SPACING should be specified)
GRID_MAX
the upper bounds for the grid (GRID_BIN or GRID_SPACING should be specified)
FULLSAMPLES
( default=500 ) number of samples in a bin prior to application of the ABF
MAXFACTOR
( default=1.0 ) maximum scaling factor of biasing force
OUTPUTFREQ
write results to a file every N steps
Options
NUMERICAL_DERIVATIVES
Generated by Doxygen
( default=off ) calculate the derivatives for these quantities numerically
532
Additional Modules
NOCZAR
( default=off ) disable the CZAR estimator
UI
( default=off ) enable the umbrella integration estimator
NOBIAS
( default=off ) DO NOT apply bias forces.
TEXTOUTPUT
( default=off ) use text output for grad and count files instead of boost←::serialization binary output
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
KAPPA
specifies that the restraint is harmonic and what the values of the force constants on each of the variables are (default to kbt/(GRID_SPACING)∧ 2)
GRID_BIN
the number of bins for the grid
GRID_SPACING
the approximate grid spacing (to be used as an alternative or together with
GRID_BIN)
ZGRID_MIN
the lower bounds for the grid (ZGRID_BIN or ZGRID_SPACING should be
specified)
ZGRID_MAX
the upper bounds for the grid (ZGRID_BIN or ZGRID_SPACING should be
specified)
ZGRID_BIN
the number of bins for the grid
ZGRID_SPACING
the approximate grid spacing (to be used as an alternative or together with
ZGRID_BIN)
EXTERNAL_FORCE
use forces from other action instead of internal spring force, this disable the
extended system!
EXTERNAL_FICT
position of external fictitious particles, useful for UIESTIMATOR
HISTORYFREQ
save history to a file every N steps
UIRESTARTPREFIX
specify the restart files for umbrella integration
OUTPUTPREFIX
specify the output prefix (default to the label name)
TEMP
the system temperature - needed when FRICTION is present. If not provided
will be taken from MD code (if available)
EXTTEMP
the temperature of extended variables (default to system temperature)
DRR_RFILE
specifies the restart file (.drrstate file)
Examples
The following input tells plumed to perform a eABF/DRR simulation on two torsional angles.
BEGIN_PLUMED_FILE
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
DRR ...
Generated by Doxygen
8.5 Extended-System Adaptive Biasing Force
533
LABEL=eabf
ARG=phi,psi
FULLSAMPLES=500
GRID_MIN=-pi,-pi
GRID_MAX=pi,pi
GRID_BIN=180,180
FRICTION=8.0,8.0
TAU=0.5,0.5
OUTPUTFREQ=50000
HISTORYFREQ=500000
... DRR
# monitor the two variables, their fictitious variables and applied forces.
PRINT STRIDE=10 ARG=phi,psi,eabf.phi_fict,eabf.psi_fict,eabf.phi_biasforce,eabf.psi_biasforce FILE=COLVAR
The following input tells plumed to perform a eABF/DRR simulation on the distance of atom 10 and 92. The distance
is restraint by LOWER_WALLS and UPPER_WALLS.
BEGIN_PLUMED_FILE
dist1: DISTANCE ATOMS=10,92
eabf_winall: DRR ARG=dist1 FULLSAMPLES=2000 GRID_MIN=1.20 GRID_MAX=3.20 GRID_BIN=200 FRICTION=8.0 TAU=0.5 OUTP
uwall: UPPER_WALLS ARG=eabf_winall.dist1_fict AT=3.2 KAPPA=418.4
lwall: LOWER_WALLS ARG=eabf_winall.dist1_fict AT=1.2 KAPPA=418.4
PRINT STRIDE=10 ARG=dist1,eabf_winall.dist1_fict,eabf_winall.dist1_biasforce FILE=COLVAR
It's also possible to run extended generalized adaptive biasing force (egABF) described in [85] . An egABF
example:
BEGIN_PLUMED_FILE
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
DRR ...
LABEL=gabf_phi
ARG=phi
FULLSAMPLES=500
GRID_MIN=-pi
GRID_MAX=pi
GRID_BIN=180
FRICTION=8.0
TAU=0.5
OUTPUTFREQ=50000
HISTORYFREQ=500000
... DRR
DRR ...
LABEL=gabf_psi
ARG=psi
FULLSAMPLES=500
GRID_MIN=-pi
GRID_MAX=pi
GRID_BIN=180
FRICTION=8.0
TAU=0.5
OUTPUTFREQ=50000
HISTORYFREQ=500000
... DRR
DRR ...
LABEL=gabf_2d
ARG=phi,psi
EXTERNAL_FORCE=gabf_phi.phi_springforce,gabf_psi.psi_springforce
EXTERNAL_FICT=gabf_phi.phi_fictNoPBC,gabf_psi.psi_fictNoPBC
GRID_MIN=-pi,-pi
GRID_MAX=pi,pi
GRID_BIN=180,180
NOBIAS
OUTPUTFREQ=50000
HISTORYFREQ=500000
... DRR
PRINT STRIDE=10 ARG=phi,psi FILE=COLVAR
Generated by Doxygen
534
Additional Modules
8.5.2
Command Line Tools
The following list contains the command line tools available in the eABF module.
drr_tool
8.5.2.1
- Extract .grad and .count files from the binary output .drrstate - Merge windows
drr_tool
This is part of the drr module
It is only available if you configure PLUMED with ./configure –enable-modules=drr . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
• Extract .grad and .count files from the binary output .drrstate
• Merge windows
Compulsory keywords
--units
( default=kj/mol ) the units of energy can be kj/mol, kcal/mol, j/mol, eV or the conversion factor from
kj/mol
Options
--help/-h
( default=off ) print this help
-v
( default=off ) Verbose output
--extract
--merge
--divergence
Extract drrstate file(s)
Merge eABF windows
Calculate divergence of gradient field (experimental)
Examples
The following command will extract .grad and .count files.
plumed drr_tool --extract eabf.drrstate
The following command will merge windows of two .drrstate file, and output the .grad and .count files.
plumed drr_tool --merge win1.drrstate,win2.drrstate
After getting the .grad and .count file, you can do numerical integration by using abf_integrate tool from https←-
://github.com/Colvars/colvars/tree/master/colvartools
abf_integrate eabf.czar.grad
Note
The abf_integrate in colvartools is in kcal/mol, so it may be better to use –units kcal/mol when running drr_tool
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
8.6
535
Variationally Enhanced Sampling (VES code)
The VES code is a module for PLUMED that implements enhanced sampling methods based on Variationally
Enhanced Sampling (VES) [69]. The VES code is developed by Omar Valsson, see the homepage of the
VES code for further information.
The VES code is an optional module that needs to be enabled when configuring the compilation of PLUMED by
using the '--enable-modules=ves' (or '--enable-modules=all') flag when running the 'configure' script.
In the tutorials you can learn how to use the methods implemented in the VES code.
The various components of the VES code module are listed and described in the following sections
• Biases
• Basis functions
• Target Distributions
• Optimizers
• Utilities
• Command Line Tools
• Tutorials
8.6.1
Biases
The following list contains the biases available in the VES code.
8.6.1.1
VES_DELTA_F
Implementation of VES ∆F method [38] (step two only).
VES_LINEAR_EXPANSION
Linear basis set expansion bias.
VES_DELTA_F
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Implementation of VES ∆F method [38] (step two only).
Warning
Notice that this is a stand-alone bias Action, it does not need any of the other VES module components
First you should create some estimate of the local free energy basins of your system, using e.g. multiple METAD
short runs, and combining them with the sum_hills utility. Once you have them, you can use this bias Action to
perform the VES optimization part of the method.
Generated by Doxygen
536
Additional Modules
These N + 1 local basins are used to model the global free energy. In particular, given the conditional probabilities
P (s|i) ∝ e−βFi (s) and the probabilities of being in a given basin Pi , we can write:
e
−βF (s)
∝ P (s) =
N
X
P (s|i)Pi .
i=0
We use this free energy model and the chosen bias factor γ to build the bias potential: V (s) = −(1 − 1/γ)F (s).
Or, more explicitly:
"
#
V (s) = (1 − 1/γ)
N
X
1
log e−βF0 (s) +
e−βFi (s) e−βαi
β
i=1
,
where the parameters α are the N free energy differences (see below) from the F0 basin.
By default the Fi (s) are shifted so that min[Fi (s)] = 0 for all i = {0, ..., N }. In this case the optimization
parameters αi are the difference in height between the minimaR of the basins. Using the keyword NORMALIZE, you
can also decide to normalize the local free energies so that ds e−βFi (s) = 1. In this case the parameters will
represent not the difference in height (which depends on the chosen CVs), but the actual free energy difference,
αi = ∆Fi .
However, as discussed in Ref. [38], a better estimate of ∆Fi should be obtained through the reweighting procedure.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
rct
the reweighting factor c(t)
work
the work done by the bias in one AV_STRIDE
Compulsory keywords
FILE_F
names of files containing local free energies and derivatives. The first one, FILE_F0, is used
as reference for all the free energy differences. You can use multiple instances of this keyword
i.e. FILE_F1, FILE_F2, FILE_F3...
BIASFACTOR
( default=0 ) the γ bias factor used for well-tempered target p(s). Set to 0 for non-tempered
flat target
M_STEP
( default=1.0 ) the µ step used for the Ω functional minimization
AV_STRIDE
( default=500 ) number of simulation steps between alpha updates
ALPHA_FILE
( default=ALPHA ) file name for output minimization parameters
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NORMALIZE
( default=off ) normalize all local free energies so that alpha will be (approx)
∆F
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
NO_MINTOZERO
537
DAMPING_OFF
( default=off ) leave local free energies as provided, without shifting them to
zero min
( default=off ) do not use an AdaGrad-like term to rescale M_STEP
SERIAL
( default=off ) perform the calculation in serial even if multiple tasks are available
MULTIPLE_WALKERS
( default=off ) use multiple walkers connected via MPI for the optimization
ARG
the input for this action is the scalar output from one or more other actions. The
particular scalars that you will use are referenced using the label of the action.
If the label appears on its own then it is assumed that the Action calculates a
single scalar value. The value of this scalar is thus used as the input to this new
action. If ∗ or ∗.∗ appears the scalars calculated by all the proceeding actions
in the input file are taken. Some actions have multi-component outputs and
each component of the output has a specific label. For example a DISTANCE
action labelled dist may have three components x, y and z. To take just the x
component you should use dist.x, if you wish to take all three components then
use dist.∗.More information on the referencing of Actions can be found in the
section of the manual on the PLUMED Getting Started. Scalar values can also
be referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED with
the appropriate flag. You can use multiple instances of this keyword i.e. ARG1,
ARG2, ARG3...
TEMP
temperature is compulsory, but it can be sometimes fetched from the MD engine
TG_STRIDE
( default=1 ) number of AV_STRIDEs between updates of target p(s) and
reweighing factor c(t)
TAU_MEAN
exponentially decaying average for alpha (rescaled using AV_STRIDE). Should
be used only in very specific cases
INITIAL_ALPHA
( default=0 ) an initial guess for the bias potential parameter alpha
PRINT_STRIDE
( default=10 ) stride for printing to ALPHA_FILE
FMT
specify format for ALPHA_FILE
RESTART
allows per-action setting of restart (YES/NO/AUTO)
Examples
The following performs the optimization of the free energy difference between two metastable basins:
BEGIN_PLUMED_FILE
VES_DELTA_F ...
LABEL=ves
ARG=cv
TEMP=300
FILE_F0=../fesA.data
FILE_F1=../fesB.data
BIASFACTOR=10.0
M_STEP=0.1
AV_STRIDE=500
PRINT_STRIDE=100
... VES_DELTA_F
PRINT FMT=%g STRIDE=500 FILE=Colvar.data ARG=cv,ves.bias,ves.rct
The local FES files can be obtained as described in Sec. 4.2 of Ref. [38], i.e. for example:
• run 4 indipendent MetaD runs, all starting from basin A, and kill them as soon as they make the first transition
(see e.g. COMMITTOR)
Generated by Doxygen
538
Additional Modules
• cat HILLS* > all_HILLS
• plumed sum_hills --hills all_HILLS --oufile all_fesA.dat --mintozero --min -1 --max 1 --bin 100
• awk -v n_rep=4 ’{if($1!="#!" && $1!="") {for(i=1+(NF-1)/2; i<=NF; i++) $i/=n_rep;} print $0}’ all_fesA.da
The header of the file should be similar to the following:
#!
#!
#!
#!
#!
FIELDS cv file.free der_cv
SET min_cv -1
SET max_cv 1
SET nbins_cv 100
SET periodic_cv false
8.6.1.2
VES_LINEAR_EXPANSION
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Linear basis set expansion bias.
This VES bias action takes the bias potential to be a linear expansion in some basis set that is written as a product
of one-dimensional basis functions. For example, for one CV the bias would be written as
V (s1 ; α) =
X
αi1 fi1 (s1 ),
i1
while for two CVs it is written as
V (s1 , s2 ; α) =
X
αi1 ,i2 fi1 (s1 ) fi2 (s2 )
i1 ,i2
where α is the set of expansion coefficients that are optimized within VES. With an appropriate choice of the basis
functions it is possible to represent any generic free energy surface. The relationship between the bias and the free
energy surface is given by
V (s) = −F (s) −
1
log p(s).
β
where p(s) is the target distribution that is employed in the VES simulation.
Basis Functions
Various one-dimensional basis functions are available in the VES code, see the complete list here. At the current
moment we recommend to use Legendre polynomials (BF_LEGENDRE) for non-periodic CVs and Fourier basis
functions (BF_FOURIER) for periodic CV (e.g. dihedral angles).
To use basis functions within VES_LINEAR_EXPANSION you first need to define them in the input file before the
VES_LINEAR_EXPANSION action and then give their labels using the BASIS_FUNCTIONS keyword.
Target Distributions
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
539
Various target distributions p(s) are available in the VES code, see the complete list here.
To use a target distribution within VES_LINEAR_EXPANSION you first need to define it in the input file before
the VES_LINEAR_EXPANSION action and then give its label using the TARGET_DISTRIBUTION keyword. The
default behavior if no TARGET_DISTRIBUTION is given is to employ a uniform target distribution.
Some target distribution, like the well-tempered one (TD_WELLTEMPERED), are dynamic and need to be iteratively
updated during the optimization.
Optimizer
In order to optimize the coefficients you will need to use VES_LINEAR_EXPANSION in combination with an optimizer, see the list of optimizers available in the VES code here. At the current moment we recommend to use the
averaged stochastic gradient decent optimizer (OPT_AVERAGED_SGD).
The optimizer should be defined after the VES_LINEAR_EXPANSION action.
Grid
Internally the code uses grids to calculate the basis set averages over the target distribution that is needed for the
gradient. The same grid is also used for the output files (see next section). The size of the grid is determined by
the GRID_BINS keyword. By default it has 100 grid points in each dimension, and generally this value should be
sufficient.
Outputting Free Energy Surfaces and Other Files
It is possible to output on-the-fly during the simulation the free energy surface estimated from the bias potential. How
often this is done is specified within the optimizer by using the FES_OUTPUT keyword. The filename is specified
by the FES_FILE keyword, but by default is it fes.LABEL.data, with an added suffix indicating the iteration number
(iter-#).
For multi-dimensional case is it possible to also output projections of the free energy surfaces. The arguments
for which to do these projections is specified using the numbered PROJ_ARG keywords. For these files a suffix
indicating the projection (proj-#) will be added to the filenames. You will also need to specify the frequency of the
output by using the FES_PROJ_OUTPUT keyword within the optimizer.
It is also possible to output the bias potential itself, for this the relevant keyword is BIAS_OUTPUT within the
optimizer. The filename is specified by the BIAS_FILE keyword, but by default is it bias.LABEL.data, with an added
suffix indicating the iteration number (iter-#).
Furthermore is it possible to output the target distribution, and its projections (i.e. marginal distributions). The
filenames of these files are specified with the TARGETDIST_FILE, but by default is it targetdist.LABEL.data. The
logarithm of the target distribution will also be outputted to file that has the added suffix log. For static target
distribution these files will be outputted in the beginning of the simulation while for dynamic ones you will need
to specify the frequency of the output by using the TARGETDIST_OUTPUT and TARGETDIST_PROJ_OUTPUT
keywords within the optimizer.
It is also possible to output free energy surfaces and bias in post processing by using the VES_OUTPUT_FES
action. However, be aware that this action does does not support dynamic target distribution (e.g. well-tempered).
Generated by Doxygen
540
Additional Modules
Static Bias
It is also possible to use VES_LINEAR_EXPANSION as a static bias that uses previously obtained coefficients. In
this case the coefficients should be read in from the coefficient file given in the COEFFS keyword.
Bias Cutoff
It is possible to impose a cutoff on the bias potential using the procedure introduced in [86] such that the free
energy surface is only flooded up to a certain value. The bias that results from this procedure can then be used as
a static bias for obtaining kinetic rates. The value of the cutoff is given by the BIAS_CUTOFF keyword. To impose
the cutoff the code uses a Fermi switching function 1/(1 + eλx ) where the parameter λ controls how sharply the
switchingfunction goes to zero. The default value is λ = 10 but this can be changed by using the BIAS_CUTOFF←_FERMI_LAMBDA keyword.
Description of components
By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input
by using this Action's label followed by a dot and the name of the quantity required from the list below.
Quantity
Description
bias
the instantaneous value of the bias potential
force2
the instantaneous value of the squared force due to this bias potential.
Compulsory keywords
BASIS_FUNCTIONS
the label of the one dimensional basis functions that should be used.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
TEMP
the system temperature - this is needed if the MD code does not pass the
temperature to PLUMED.
BIAS_FILE
filename of the file on which the bias should be written out. By default
it is bias.LABEL.data. Note that suffixes indicating the iteration number
(iter-#) are added to the filename when optimizing coefficients.
FES_FILE
filename of the file on which the FES should be written out. By default it is
fes.LABEL.data. Note that suffixes indicating the iteration number (iter-#)
are added to the filename when optimizing coefficients.
TARGETDIST_FILE
filename of the file on which the target distribution should be written out.
By default it is targetdist.LABEL.data. Note that suffixes indicating the
iteration number (iter-#) are added to the filename when optimizing coefficients and the target distribution is dynamic.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
541
COEFFS
TARGET_DISTRIBUTION
read in the coefficients from files.
the label of the target distribution to be used.
BIAS_CUTOFF
cutoff the bias such that it only fills the free energy surface up to certain
level F_cutoff, here you should give the value of the F_cutoff.
BIAS_CUTOFF_FERMI_LAMBDA
the lambda value used in the Fermi switching function for the bias cutoff
(BIAS_CUTOFF), the default value is 10.0.
GRID_BINS
the number of bins used for the grid. The default value is 100 bins per
dimension.
arguments for doing projections of the FES or the target distribution. You
can use multiple instances of this keyword i.e. PROJ_ARG1, PROJ_A←RG2, PROJ_ARG3...
PROJ_ARG
ARG
the input for this action is the scalar output from one or more other actions.
The particular scalars that you will use are referenced using the label of
the action. If the label appears on its own then it is assumed that the Action calculates a single scalar value. The value of this scalar is thus used
as the input to this new action. If ∗ or ∗.∗ appears the scalars calculated
by all the proceeding actions in the input file are taken. Some actions
have multi-component outputs and each component of the output has a
specific label. For example a DISTANCE action labelled dist may have
three components x, y and z. To take just the x component you should
use dist.x, if you wish to take all three components then use dist.∗.More
information on the referencing of Actions can be found in the section of
the manual on the PLUMED Getting Started. Scalar values can also be
referenced using POSIX regular expressions as detailed in the section on
Regular Expressions. To use this feature you you must compile PLUMED
with the appropriate flag. You can use multiple instances of this keyword
i.e. ARG1, ARG2, ARG3...
Examples
In the following example we run a VES_LINEAR_EXPANSION for one CV using a Legendre basis functions
(BF_LEGENDRE) and a uniform target distribution as no target distribution is specified. The coefficients are optimized using averaged stochastic gradient descent optimizer (OPT_AVERAGED_SGD). Within the optimizer we
specify that the FES should be outputted to file every 500 coefficients iterations (the FES_OUTPUT keyword). Parameters that are very specific to the problem at hand, like the order of the basis functions, the interval on which the
basis functions are defined, and the step size used in the optimizer, are left unfilled.
BEGIN_PLUMED_FILE
bf1: BF_LEGENDRE ORDER=__ MINIMUM=__ MAXIMUM=__
VES_LINEAR_EXPANSION ...
ARG=d1
BASIS_FUNCTIONS=bf1
TEMP=__
GRID_BINS=200
LABEL=b1
... VES_LINEAR_EXPANSION
OPT_AVERAGED_SGD ...
BIAS=b1
STRIDE=1000
LABEL=o1
STEPSIZE=__
FES_OUTPUT=500
COEFFS_OUTPUT=10
... OPT_AVERAGED_SGD
Generated by Doxygen
542
Additional Modules
In the following example we employ VES_LINEAR_EXPANSION for two CVs, The first CV is periodic and therefore
we employ a Fourier basis functions (BF_LEGENDRE) while the second CV is non-periodic so we employ a Legendre polynomials as in the previous example. For the target distribution we employ a well-tempered target distribution
(TD_WELLTEMPERED), which is dynamic and needs to be iteratively updated with a stride that is given using the
TARGETDIST_STRIDE within the optimizer.
BEGIN_PLUMED_FILE
bf1: BF_FOURIER ORDER=__ MINIMUM=__ MAXIMUM=__
bf2: BF_LEGENDRE ORDER=__ MINIMUM=__ MAXIMUM=__
td_wt: TD_WELLTEMPERED BIASFACTOR=10.0
VES_LINEAR_EXPANSION ...
ARG=cv1,cv2
BASIS_FUNCTIONS=bf1,bf2
TEMP=__
GRID_BINS=100
LABEL=b1
TARGET_DISTRIBUTION=td_wt
... VES_LINEAR_EXPANSION
OPT_AVERAGED_SGD ...
BIAS=b1
STRIDE=1000
LABEL=o1
STEPSIZE=__
FES_OUTPUT=500
COEFFS_OUTPUT=10
TARGETDIST_STRIDE=500
... OPT_AVERAGED_SGD
In the following example we employ a bias cutoff such that the bias only fills the free energy landscape up a certain
level. In this case the target distribution is also dynamic and needs to iteratively updated.
BEGIN_PLUMED_FILE
bf1: BF_LEGENDRE ORDER=__ MINIMUM=__ MAXIMUM=__
bf2: BF_LEGENDRE ORDER=__ MINIMUM=__ MAXIMUM=__
VES_LINEAR_EXPANSION ...
ARG=cv1,cv2
BASIS_FUNCTIONS=bf1,bf2
TEMP=__
GRID_BINS=100
LABEL=b1
BIAS_CUTOFF=20.0
... VES_LINEAR_EXPANSION
OPT_AVERAGED_SGD ...
BIAS=b1
STRIDE=1000
LABEL=o1
STEPSIZE=__
FES_OUTPUT=500
COEFFS_OUTPUT=10
TARGETDIST_STRIDE=500
... OPT_AVERAGED_SGD
The optimized bias potential can then be used as a static bias for obtaining kinetics. For this you need read in the
final coefficients from file (e.g. coeffs_final.data in this case) by using the COEFFS keyword (also, no optimizer
should be defined in the input)
BEGIN_PLUMED_FILE
bf1: BF_LEGENDRE ORDER=__ MINIMUM=__ MAXIMUM=__
bf2: BF_LEGENDRE ORDER=__ MINIMUM=__ MAXIMUM=__
VES_LINEAR_EXPANSION ...
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
543
ARG=cv1,cv2
BASIS_FUNCTIONS=bf1,bf2
TEMP=__
GRID_BINS=100
LABEL=b1
BIAS_CUTOFF=20.0
COEFFS=coeffs_final.data
... VES_LINEAR_EXPANSION
8.6.2
Basis functions
The following list contains the one-dimensional basis functions available in the VES code.
BF_CHEBYSHEV_RATIONAL_FULL_INFINITE
Rational Chebyshev basis functions on a full-infinite interval
BF_CHEBYSHEV_RATIONAL_SEMI_INFINITE
Rational Chebyshev basis functions on a semi-infinite interval
BF_CHEBYSHEV
Chebyshev polynomial basis functions.
BF_COMBINED
Combining other basis functions types
BF_COSINE
BF_CUBIC_B_SPLINES
Fourier cosine basis functions.
Cubic B spline basis functions
BF_CUSTOM
Basis functions given by arbitrary mathematical expressions.
BF_FOURIER
BF_HERMITE
BF_LAGUERRE
Fourier basis functions.
Hermite basis functions.
Laguerre basis functions.
BF_LEGENDRE
Legendre polynomials basis functions.
BF_POWERS
Polynomial power basis functions.
BF_SINE
Fourier sine basis functions.
8.6.2.1
BF_CHEBYSHEV_RATIONAL_FULL_INFINITE
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Rational Chebyshev basis functions on a full-infinite interval
Compulsory keywords
ORDER
The order of the basis function expansion.
MINIMUM
MAXIMUM
MAP_PARAMETER
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
Constant map parameter that defines the interval on which is the bias is active (should
match the width of the function to be expanded).
Options
Generated by Doxygen
544
Additional Modules
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for
debugging.
NUMERICAL_INTEGRALS
( default=off ) Calculate basis function integral for the uniform distribution numerically. Useful for debugging.
CENTER
the location of the center of the Hermite functions. By default it is 0.0
Examples
8.6.2.2
BF_CHEBYSHEV_RATIONAL_SEMI_INFINITE
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Rational Chebyshev basis functions on a semi-infinite interval
Compulsory keywords
ORDER
The order of the basis function expansion.
MINIMUM
MAXIMUM
MAP_PARAMETER
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
Constant map parameter that defines the interval on which is the bias is active (should
match the width of the function to be expanded).
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for
debugging.
NUMERICAL_INTEGRALS
( default=off ) Calculate basis function integral for the uniform distribution numerically. Useful for debugging.
Examples
8.6.2.3
BF_CHEBYSHEV
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
545
Chebyshev polynomial basis functions.
Use as basis functions Chebyshev polynomials of the first kind Tn (x) defined on a bounded interval. You
need to provide the interval [a, b] on which the basis functions are to be used, and the order of the expansion N
(i.e. the highest order polynomial used). The total number of basis functions is N + 1 as the constant T0 (x) = 1 is
also included. These basis functions should not be used for periodic CVs.
Intrinsically the Chebyshev polynomials are defined on the interval [−1, 1]. A variable t in the interval [a, b] is
transformed to a variable x in the intrinsic interval [−1, 1] by using the transform function
x(t) =
t − (a + b)/2
(b − a)/2
The Chebyshev polynomials are given by the recurrence relation T0 (x) = 1
T1 (x) = x
Tn+1 (x) = 2 x Tn (x) − Tn−1 (x)
The first 6 polynomials are shown below
The Chebyshev polynomial are orthogonal over the interval [−1, 1] with respect to the weight
Z
1
dx Tn (x) Tm (x) √
−1
√ 1
1−x2
1
= { 0 n 6= mπn = m = 0π/2n = m 6= 0
1 − x2
For further mathematical properties of the Chebyshev polynomials see for example the Wikipedia page.
Compulsory keywords
ORDER
The order of the basis function expansion.
MINIMUM
MAXIMUM
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for
debugging.
NUMERICAL_INTEGRALS
( default=off ) Calculate basis function integral for the uniform distribution numerically. Useful for debugging.
Examples
Here we employ a Chebyshev expansion of order 20 over the interval 0.0 to 10.0. This results in a total number of
21 basis functions. The label used to identify the basis function action can then be referenced later on in the input
file.
BEGIN_PLUMED_FILE
bfC: BF_CHEBYSHEV MINIMUM=0.0 MAXIMUM=10.0 ORDER=20
Generated by Doxygen
546
Additional Modules
8.6.2.4
BF_COMBINED
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Combining other basis functions types
Compulsory keywords
BASIS_FUNCTIONS
Labels of the basis functions that should be combined. Note that the order used matters
for the ordering of the basis functions. This needs to be kept in mind when restarting
from previous coefficients.
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for debugging.
Examples
Here we define both Fourier cosine and sine expansions of order 10, each with 11 basis functions, which are
combined. This results in a total number of 21 basis functions as only the constant from is bf_cos is used.
BEGIN_PLUMED_FILE
bf_cos: BF_COSINE MINIMUM=-pi MAXIMUM=+pi ORDER=10
bf_sin: BF_SINE
MINIMUM=-pi MAXIMUM=+pi ORDER=10
bf_comb: BF_COMBINED BASIS_FUNCTIONS=bf_cos,bf_sin
In principle this is the same as using BF_FOURIER with ORDER=10 but with different ordering of the basis functions. Note that the order used in BASIS_FUNCTIONS matters for the ordering of the basis functions, using BAS←IS_FUNCTIONS=bf_sin,bf_cos would results in a different order of the basis functions. This should be kept in mind
when restarting from previous coefficients.
8.6.2.5
BF_COSINE
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Fourier cosine basis functions.
Use as basis functions Fourier cosine series defined on a periodic interval. You need to provide the periodic interval
[a, b] on which the basis functions are to be used, and the order of the expansion N (i.e. the highest Fourier cosine
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
547
mode used). The total number of basis functions is N + 1 as the constant f0 (x) = 1 is also included. These basis
functions should only be used for periodic CVs. They can be useful if the periodic function being expanded is an
even function, i.e. F (−x) = F (x).
The Fourier cosine basis functions are given by f0 (x) = 1
f1 (x) = cos( 2π
P x)
f2 (x) = cos(2 · 2π
P x)
f3 (x) = cos(3 · 2π
P x)
..
.
fn (x) = cos(n ·
2π
P x)
..
.
fN (x) = cos(N ·
2π
P x)
where P = (b − a) is the periodicity of the interval. They are orthogonal over the interval [a, b]
Z
b
dx fn (x) fm (x) = { 0 n 6= m(b − a)n = m = 0(b − a)/2n = m 6= 0.
a
Compulsory keywords
ORDER
The order of the basis function expansion.
MINIMUM
MAXIMUM
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for
debugging.
NUMERICAL_INTEGRALS
( default=off ) Calculate basis function integral for the uniform distribution numerically. Useful for debugging.
Examples
Here we employ a Fourier cosine expansion of order 10 over the periodic interval −π to +π . This results in a total
number of 11 basis functions. The label used to identify the basis function action can then be referenced later on in
the input file.
BEGIN_PLUMED_FILE
BF_COSINE MINIMUM=-pi MAXIMUM=+pi ORDER=10 LABEL=bf1
8.6.2.6
BF_CUBIC_B_SPLINES
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Generated by Doxygen
548
Additional Modules
Cubic B spline basis functions
Compulsory keywords
ORDER
The order of the basis function expansion.
MINIMUM
MAXIMUM
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for debugging.
NORMALIZATION
the normalization factor that is used to normalize the basis functions by dividing the values.
By default it is 2.
Examples
Test
8.6.2.7
BF_CUSTOM
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Basis functions given by arbitrary mathematical expressions.
This allows you to define basis functions using arbitrary mathematical expressions that are parsed using the lepton
library. The basis functions fi (x) are given in mathematical expressions with x as a variable using the numbered
FUNC keywords that start from FUNC1. Consistent with other basis functions is f0 (x) = 1 defined as the constant.
The interval on which the basis functions are defined is given using the MINIMUM and MAXIMUM keywords.
Using the TRANSFORM keyword it is possible to define a function x(t) that is used to transform the argument
before calculating the basis functions values. The variables min and max can be used to indicate the minimum and
the maximum of the interval. By default the arguments are not transformed, i.e. x(t) = t.
For periodic basis functions you should use the PERIODIC flag to indicate that they are periodic.
The basis functions fi (x) and the transform function x(t) need to be well behaved in the interval on which the basis
functions are defined, e.g. not result in a not a number (nan) or infinity (inf). The code will not perform checks to
make sure that this is the case unless the flag CHECK_NAN_INF is enabled.
Compulsory keywords
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
MINIMUM
MAXIMUM
549
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for debugging.
PERIODIC
( default=off ) Indicate that the basis functions are periodic.
CHECK_NAN_INF
( default=off ) Check that the basis functions do not result in a not a number (nan) or infinity
(inf).
FUNC
The basis functions f_i(x) given in mathematical expressions using x as a variable. You
can use multiple instances of this keyword i.e. FUNC1, FUNC2, FUNC3...
TRANSFORM
An optional function that can be used to transform the argument before calculating the
basis function values. You should use t as a variable. You can use the variables min and
max to give the minimum and the maximum of the interval.
Examples
Defining Legendre polynomial basis functions of order 6 using BF_CUSTOM where the appropriate transform function is given by the TRANSFORM keyword. This is just an example of what can be done, in practice you should use
BF_LEGENDRE for Legendre polynomial basis functions.
BEGIN_PLUMED_FILE
BF_CUSTOM ...
TRANSFORM=(t-(min+max)/2)/((max-min)/2)
FUNC1=x
FUNC2=(1/2)*(3*x^2-1)
FUNC3=(1/2)*(5*x^3-3*x)
FUNC4=(1/8)*(35*x^4-30*x^2+3)
FUNC5=(1/8)*(63*x^5-70*x^3+15*x)
FUNC6=(1/16)*(231*x^6-315*x^4+105*x^2-5)
MINIMUM=-4.0
MAXIMUM=4.0
LABEL=bf1
... BF_CUSTOM
Defining Fourier basis functions of order 3 using BF_CUSTOM where the periodicity is indicated using the PERI←ODIC flag. This is just an example of what can be done, in practice you should use BF_FOURIER for Fourier basis
functions.
BEGIN_PLUMED_FILE
BF_CUSTOM ...
FUNC1=cos(x)
FUNC2=sin(x)
FUNC3=cos(2*x)
FUNC4=sin(2*x)
FUNC5=cos(3*x)
FUNC6=sin(3*x)
MINIMUM=-pi
MAXIMUM=+pi
LABEL=bf1
PERIODIC
... BF_CUSTOM
8.6.2.8
BF_FOURIER
Generated by Doxygen
550
Additional Modules
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Fourier basis functions.
Use as basis functions Fourier series defined on a periodic interval. You need to provide the periodic interval [a, b]
on which the basis functions are to be used, and the order of the expansion N (i.e. the highest Fourier mode used).
The total number of basis functions is 2N + 1 as for each Fourier mode there is both the cosine and sine term, and
the constant f0 (x) = 1 is also included. These basis functions should only be used for periodic CVs.
The Fourier series basis functions are given by f0 (x) = 1
f1 (x) = cos( 2π
P x)
f2 (x) = sin( 2π
P x)
f3 (x) = cos(2 · 2π
P x)
f4 (x) = sin(2 · 2π
P x)
..
.
f2k−1 (x) = cos(k · 2π
P x)
f2k (x) = sin(k · 2π
x)
P
..
.
f2N −1 (x) = cos(N · 2π
P x)
f2N (x) = sin(N · 2π
P x)
where P = (b − a) is the periodicity of the interval. They are orthogonal over the interval [a, b]
Z
b
dx fn (x) fm (x) = { 0 n 6= m(b − a)n = m = 0(b − a)/2n = m 6= 0.
a
Compulsory keywords
ORDER
The order of the basis function expansion.
MINIMUM
MAXIMUM
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for
debugging.
NUMERICAL_INTEGRALS
( default=off ) Calculate basis function integral for the uniform distribution numerically. Useful for debugging.
Examples
Here we employ a Fourier expansion of order 10 over the periodic interval −π to +π . This results in a total number
of 21 basis functions. The label used to identify the basis function action can then be referenced later on in the input
file.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
551
BEGIN_PLUMED_FILE
BF_FOURIER MINIMUM=-pi MAXIMUM=+pi ORDER=10 LABEL=bf_fourier
8.6.2.9
BF_HERMITE
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Hermite basis functions.
Compulsory keywords
ORDER
The order of the basis function expansion.
MINIMUM
MAXIMUM
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for debugging.
SCALING_FACTOR
scaling factor that is used to define the length scale of the basis functions. Depends also
on the order employed. By default it is 1.0
CENTER
the location of the center of the Hermite functions. By default it is 0.0
Examples
8.6.2.10
BF_LAGUERRE
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Laguerre basis functions.
Compulsory keywords
ORDER
The order of the basis function expansion.
MINIMUM
MAXIMUM
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
Generated by Doxygen
552
Additional Modules
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for debugging.
SCALING_FACTOR
scaling factor that is used to define the length scale of the basis functions. Depends also
on the order employed. By default it is 1.0
Examples
8.6.2.11
BF_LEGENDRE
Legendre polynomials basis functions.
Use as basis functions Legendre polynomials Pn (x) defined on a bounded interval. You need to provide
the interval [a, b] on which the basis functions are to be used, and the order of the expansion N (i.e. the highest
order polynomial used). The total number of basis functions is N + 1 as the constant P0 (x) = 1 is also included.
These basis functions should not be used for periodic CVs.
Intrinsically the Legendre polynomials are defined on the interval [−1, 1]. A variable t in the interval [a, b] is transformed to a variable x in the intrinsic interval [−1, 1] by using the transform function
x(t) =
t − (a + b)/2
(b − a)/2
The Legendre polynomials are given by the recurrence relation P0 (x) = 1
P1 (x) = x
Pn+1 (x) =
2n+1
n+1
x Pn (x) −
n
n+1
Pn−1 (x)
The first 6 polynomials are shown below
The Legendre polynomial are orthogonal over the interval [−1, 1]
Z
1
dx Pn (x) Pm (x) =
−1
2
δn,m
2n + 1
q
By using the SCALED keyword the polynomials are scaled by a factor of
1.
2n+1
2
such that they are orthonormal to
From the above equation it follows that integral of the basis functions over the uniform target distribution pu (x) are
given by
Z
1
dx Pn (x)pu (x) = δn,0 ,
−1
and thus always zero except for the constant P0 (x) = 1.
For further mathematical properties of the Legendre polynomials see for example the Wikipedia page.
Compulsory keywords
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
ORDER
The order of the basis function expansion.
MINIMUM
MAXIMUM
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
553
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for
debugging.
NUMERICAL_INTEGRALS
( default=off ) Calculate basis function integral for the uniform distribution numerically. Useful for debugging.
SCALED
( default=off ) Scale the polynomials such that they are orthonormal to 1.
Examples
Here we employ a Legendre expansion of order 20 over the interval -4.0 to 8.0. This results in a total number of 21
basis functions. The label used to identify the basis function action can then be referenced later on in the input file.
BEGIN_PLUMED_FILE
bf_leg: BF_LEGENDRE MINIMUM=-4.0 MAXIMUM=8.0 ORDER=20
Examples
8.6.2.12
BF_POWERS
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Polynomial power basis functions.
Attention
These basis functions should not be used in conventional biasing simulations. Instead you should use
orthogonal basis functions like Legendre or Chebyshev polynomials. They are only included for usage in
ves_md_linearexpansion and some special cases.
Basis functions given by polynomial powers defined on a bounded interval. You need to provide the interval [a, b]
on which the basis functions are to be used, and the order of the expansion N (i.e. the highest power used). The
total number of basis functions is N + 1 as the constant f0 (x) = 1 is also included. These basis functions should
not be used for periodic CVs.
The basis functions are given by f0 (x) = 1
f1 (x) = x
Generated by Doxygen
554
Additional Modules
f2 (x) = x2
..
.
fn (x) = xn
..
.
fN (x) = xN
Note that these basis functions are not orthogonal. In fact the integral over the uniform target distribution blows up
as the interval is increased. Therefore they should not be used in conventional biasing simulations. However, they
can be useful for usage with ves_md_linearexpansion.
Compulsory keywords
ORDER
The order of the basis function expansion.
MINIMUM
MAXIMUM
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for debugging.
NORMALIZATION
The normalization factor that is used to normalize the basis functions. By default it is 1.0.
Examples
Here we employ a polynomial power expansion of order 5 over the interval -2.0 to 2.0. This results in a total number
of 6 basis functions. The label used to identify the basis function action can then be referenced later on in the input
file.
BEGIN_PLUMED_FILE
BF_POWERS MINIMUM=-2.0 MAXIMUM=2.0 ORDER=5 LABEL=bf_pow
8.6.2.13
BF_SINE
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Fourier sine basis functions.
Use as basis functions Fourier sine series defined on a periodic interval. You need to provide the periodic interval
[a, b] on which the basis functions are to be used, and the order of the expansion N (i.e. the highest Fourier sine
mode used). The total number of basis functions is N + 1 as the constant f0 (x) = 1 is also included. These basis
functions should only be used for periodic CVs. They can be useful if the periodic function being expanded is an
odd function, i.e. F (−x) = −F (x).
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
555
The Fourier sine basis functions are given by f0 (x) = 1
f1 (x) = sin( 2π
P x)
f2 (x) = sin(2 · 2π
P x)
f3 (x) = sin(3 · 2π
P x)
..
.
fn (x) = sin(n ·
2π
P x)
..
.
fN (x) = sin(N · 2π
P x)
where P = (b − a) is the periodicity of the interval. They are orthogonal over the interval [a, b]
Z
b
dx fn (x) fm (x) = { 0 n 6= m(b − a)n = m = 0(b − a)/2n = m 6= 0.
a
Compulsory keywords
ORDER
The order of the basis function expansion.
MINIMUM
MAXIMUM
The minimum of the interval on which the basis functions are defined.
The maximum of the interval on which the basis functions are defined.
Options
DEBUG_INFO
( default=off ) Print out more detailed information about the basis set. Useful for
debugging.
NUMERICAL_INTEGRALS
( default=off ) Calculate basis function integral for the uniform distribution numerically. Useful for debugging.
Examples
Here we employ a Fourier sine expansion of order 10 over the periodic interval −π to +π . This results in a total
number of 11 basis functions. The label used to identify the basis function action can then be referenced later on in
the input file.
BEGIN_PLUMED_FILE
BF_SINE MINIMUM=-pi MAXIMUM=+pi ORDER=10 LABEL=bfS
Examples
8.6.3
Target Distributions
The following list contains the target distributions available in the VES code.
Generated by Doxygen
556
Additional Modules
TD_CHISQUARED
Chi-squared distribution (static).
TD_CHI
Chi distribution (static).
TD_CUSTOM
Target distribution given by an arbitrary mathematical expression (static or dynamic).
TD_EXPONENTIALLY_MODIFIED_GAUSSIAN
Target distribution given by a sum of exponentially modified
Gaussian distributions (static).
TD_EXPONENTIAL
Exponential distribution (static).
TD_GAUSSIAN
Target distribution given by a sum of Gaussian kernels
(static).
TD_GENERALIZED_EXTREME_VALUE
Generalized extreme value distribution (static).
TD_GENERALIZED_NORMAL
Target distribution given by a sum of generalized normal distributions (static).
TD_GRID
Target distribution from an external grid file (static).
TD_LINEAR_COMBINATION
Target distribution given by linear combination of distributions
(static or dynamic).
TD_MARGINAL_WELLTEMPERED
One-dimensional marginal well-tempered target distribution
(dynamic).
TD_PRODUCT_COMBINATION
Target distribution given by product combination of distributions (static or dynamic).
TD_PRODUCT_DISTRIBUTION
Target distribution given by a separable product of onedimensional distributions (static or dynamic).
TD_UNIFORM
Uniform target distribution (static).
TD_VONMISES
Target distribution given by a sum of Von Mises distributions
(static).
TD_WELLTEMPERED
Well-tempered target distribution (dynamic).
8.6.3.1
TD_CHISQUARED
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Chi-squared distribution (static).
Employ a target distribution given by a chi-squared distribution that is defined as
p(s) =
1
k
σ 22 Γ
k
2
s−a
σ
k2 −1
1
exp −
2
s−a
σ
,
where a is the minimum of the distribution that is defined on the interval [a, ∞), the parameter k (given as a positive
integer larger than 2) determines how far the peak of the distribution is from the minimum (known as the "degrees
of freedom"), and the parameter σ > 0 determines the broadness of the distribution.
The minimum a is given using the MINIMUM keyword, the parameter k is given using the KAPPA keyword, and the
parameter σ is given using the SIGMA keyword.
This target distribution action is only defined for one dimension, for multiple dimensions it should be used in combination with the TD_PRODUCT_DISTRIBUTION action.
Compulsory keywords
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
557
MINIMUM
The minimum of the chi-squared distribution.
SIGMA
The σ parameter of the chi-squared distribution given as a positive number.
KAPPA
The k parameter of the chi-squared distribution given as positive integer larger than 2.
Options
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
NORMALIZE
( default=off ) Renormalized the target distribution over the intervals on which
it is defined to make sure that it is properly normalized to 1. In most cases this
should not be needed as the target distributions should be normalized. The
code will issue a warning (but still run) if this is needed for some reason.
WELLTEMPERED_FACTOR
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
Examples
Chi-squared distribution with a = −10.0, σ = 2.0, and k = 2
BEGIN_PLUMED_FILE
td: TD_CHISQUARED
MINIMUM=-10.0
SIGMA=2.0
KAPPA=2
The Chi-squared distribution is only defined for one dimension so for multiple dimensions we have to use it in
combination with the TD_PRODUCT_DISTRIBUTION action as shown in the following example where we have a
Chi-squared distribution for argument 1 and uniform distribution for argument 2
BEGIN_PLUMED_FILE
td_chisq: TD_CHISQUARED
MINIMUM=10.0
SIGMA=2.0
KAPPA=2
td_uni: TD_UNIFORM
td_pd: TD_PRODUCT_DISTRIBUTION DISTRIBUTIONS=td_chisq,td_uni
8.6.3.2
TD_CHI
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Chi distribution (static).
Employ a target distribution given by a chi distribution that is defined as
k
21− 2
p(s) =
σ Γ k2
Generated by Doxygen
s−a
σ
k−1
1
exp −
2
s−a
σ
2 !
,
558
Additional Modules
where a is the minimum of the distribution that is defined on the interval [a, ∞), the parameter k (given as a positive
integer larger than 1) determines how far the peak of the distribution is from the minimum (known as the "degrees
of freedom"), and the parameter σ > 0 determines the broadness of the distribution.
The minimum a is given using the MINIMUM keyword, the parameter k is given using the KAPPA keyword, and the
parameter σ is given using the SIGMA keyword.
This target distribution action is only defined for one dimension, for multiple dimensions it should be used in combination with the TD_PRODUCT_DISTRIBUTION action.
Compulsory keywords
MINIMUM
SIGMA
The minimum of the chi distribution.
The σ parameter of the chi distribution given as a positive number.
KAPPA
The k parameter of the chi distribution given as positive integer larger than 1.
Options
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
NORMALIZE
( default=off ) Renormalized the target distribution over the intervals on which
it is defined to make sure that it is properly normalized to 1. In most cases this
should not be needed as the target distributions should be normalized. The
code will issue a warning (but still run) if this is needed for some reason.
WELLTEMPERED_FACTOR
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
Examples
Chi distribution with a = 10.0, σ = 2.0, and k = 2
BEGIN_PLUMED_FILE
td: TD_CHI MINIMUM=10.0
SIGMA=2.0
KAPPA=2
The Chi distribution is only defined for one dimension so for multiple dimensions we have to use it in combination with
the TD_PRODUCT_DISTRIBUTION action as shown in the following example where we have a uniform distribution
for argument 1 and a Chi distribution for argument 1
BEGIN_PLUMED_FILE
td_uni: TD_UNIFORM
td_chi: TD_CHI
MINIMUM=-10.0
SIGMA=2.0
KAPPA=2
td_pd: TD_PRODUCT_DISTRIBUTION DISTRIBUTIONS=td_uni,td_chi
8.6.3.3
TD_CUSTOM
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
559
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Target distribution given by an arbitrary mathematical expression (static or dynamic).
Use as a target distribution the distribution defined by
p(s) = R
f (s)
ds f (s)
where f (s) is some arbitrary mathematical function that is parsed by the lepton library.
The function f (s) is given by the FUNCTION keywords by using s1,s2,..., as variables for the arguments s =
(s1 , s2 , . . . , sd ). If one variable is not given the target distribution will be taken as uniform in that argument.
It is also possible to include the free energy surface F (s) in the target distribution by using the FE variable. In this
case the target distribution is dynamic and needs to be updated with current best estimate of F (s), similarly as for
the well-tempered target distribution. Furthermore, the inverse temperature β = (kB T )−1 and the thermal energy
kB T can be included by using the beta and kB T variables.
The target distribution will be automatically normalized over the region on which it is defined on. Therefore, the
function given in FUNCTION needs to be non-negative and it must be possible to normalize the function. The code
will perform checks to make sure that this is indeed the case.
Compulsory keywords
FUNCTION
The function you wish to use for the target distribution where you should use the variables s1,s2,...
for the arguments. You can also use the current estimate of the FES by using the variable FE and
the temperature by using the kB T and beta variables.
Options
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
WELLTEMPERED_FACTOR
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
Examples
Here we use as shifted Maxwell-Boltzmann distribution as a target distribution in one-dimension. Note
that it is not need to include the normalization factor as the distribution will be automatically normalized.
BEGIN_PLUMED_FILE
Generated by Doxygen
560
Additional Modules
TD_CUSTOM ...
FUNCTION=(s1+20)^2*exp(-(s1+20)^2/(2*10.0^2))
LABEL=td
... TD_CUSTOM
Here we have a two dimensional target distribution where we use a generalized normal distribution
for argument s2 while the distribution for s1 is taken as uniform as the variable s1 is not included in the function.
BEGIN_PLUMED_FILE
TD_CUSTOM ...
FUNCTION=exp(-(abs(s2-20.0)/5.0)^4.0)
LABEL=td
... TD_CUSTOM
By using the FE variable the target distribution can depend on the free energy surface F (s). For example, the
following input is identical to using TD_WELLTEMPERED with a bias factor of 10.
BEGIN_PLUMED_FILE
TD_CUSTOM ...
FUNCTION=exp(-(beta/10.0)*FE)
LABEL=td
... TD_CUSTOM
Here the inverse temperature is automatically obtained by using the beta variable. It is also possible to use the kB T
variable. The following syntax will give the exact same results as the syntax above
BEGIN_PLUMED_FILE
TD_CUSTOM ...
FUNCTION=exp(-(1.0/(kBT*10.0))*FE)}
LABEL=td
... TD_CUSTOM
8.6.3.4
TD_EXPONENTIALLY_MODIFIED_GAUSSIAN
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Target distribution given by a sum of exponentially modified Gaussian distributions (static).
Employ a target distribution that is given by a sum where each term is a product of one-dimensional
exponentially modified Gaussian distributions,
p(s) =
X
i
wi
d
Y
λk,i
k
2
"
#
2
µk,i + λk,i σk,i
− sk )
λk,i
2
√
exp
(2µk,i + λk,i σk,i − 2sk ) erfc
2
2σk,i
where (µ1,i , µ2,i , . . . , µd,i ) are the centers of the Gaussian component, (σ1,i , σ2,i , . . . , σd,i ) are the standard
deviations of the Gaussian component, (λ1,i , λ2,i , . . . , λd,i ) are the rate parameters of the exponential
Pcomponent,
and erfc(x) = 1 − erf(x) is the complementary error function. The weights wi are normalized to 1, i wi = 1.
The centers (µ1,i , µ2,i , . . . , µd,i ) are given using the numbered CENTER keywords, the standard deviations
(σ1,i , σ2,i , . . . , σd,i ) using the the numbered SIGMA keywords, and the rate parameters (λ1,i , λ2,i , . . . , λd,i ) using
the numbered LAMBDA keywords. The weights are given using the WEIGHTS keywords, if no weights are given
are all terms weighted equally.
Options
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
561
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
NORMALIZE
( default=off ) Renormalized the target distribution over the intervals on which
it is defined to make sure that it is properly normalized to 1. In most cases this
should not be needed as the target distributions should be normalized. The
code will issue a warning (but still run) if this is needed for some reason.
CENTER
The center of each exponentially modified Gaussian distributions. You can use
multiple instances of this keyword i.e. CENTER1, CENTER2, CENTER3...
SIGMA
The sigma parameters for each exponentially modified Gaussian distributions.
You can use multiple instances of this keyword i.e. SIGMA1, SIGMA2, SIGM←A3...
The lambda parameters for each exponentially modified Gaussian distributions
You can use multiple instances of this keyword i.e. LAMBDA1, LAMBDA2, L←AMBDA3...
The weights of the distributions. By default all are weighted equally.
LAMBDA
WEIGHTS
WELLTEMPERED_FACTOR
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
Examples
An exponentially modified Gaussian distribution in one-dimension
BEGIN_PLUMED_FILE
td1: TD_EXPONENTIALLY_MODIFIED_GAUSSIAN CENTER1=-10.0 SIGMA1=1.0 LAMBDA1=0.25
A sum of two one-dimensional exponentially modified Gaussian distributions
BEGIN_PLUMED_FILE
TD_EXPONENTIALLY_MODIFIED_GAUSSIAN ...
CENTER1=-10.0 SIGMA1=1.0 LAMBDA1=0.5
CENTER2=+10.0 SIGMA2=1.0 LAMBDA2=1.0
WEIGHTS=2.0,1.0
LABEL=td1
... TD_EXPONENTIALLY_MODIFIED_GAUSSIAN
A sum of two two-dimensional exponentially modified Gaussian distributions
BEGIN_PLUMED_FILE
TD_EXPONENTIALLY_MODIFIED_GAUSSIAN ...
CENTER1=-5.0,+5.0 SIGMA1=1.0,1.0 LAMBDA1=0.5,0.5
CENTER2=+5.0,+5.0 SIGMA2=1.0,1.0 LAMBDA2=1.0,1.0
WEIGHTS=1.0,1.0
LABEL=td1
... TD_EXPONENTIALLY_MODIFIED_GAUSSIAN
8.6.3.5
TD_EXPONENTIAL
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Generated by Doxygen
562
Additional Modules
Exponential distribution (static).
Employ a target distribution given by an exponential distribution that is defined as
p(s) = λe−λ(s−a)
where a is the minimum of the distribution that is defined on the interval [a, ∞), and λ > 0 is the so-called rate
parameter.
The minimum a is given using the MINIMUM keyword, and the rate parameter λ is given using the LAMBDA keyword.
This target distribution action is only defined for one dimension, for multiple dimensions it should be used in combination with TD_PRODUCT_DISTRIBUTION action.
Compulsory keywords
MINIMUM
The minimum of the exponential distribution.
LAMBDA
The λ parameter of the exponential distribution given as positive number.
Options
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
NORMALIZE
( default=off ) Renormalized the target distribution over the intervals on which
it is defined to make sure that it is properly normalized to 1. In most cases this
should not be needed as the target distributions should be normalized. The
code will issue a warning (but still run) if this is needed for some reason.
WELLTEMPERED_FACTOR
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
Examples
Exponential distribution with a = 10.0 and λ = 0.5
BEGIN_PLUMED_FILE
td: TD_EXPONENTIAL
MINIMUM=-10.0
LAMBDA=0.5
The exponential distribution is only defined for one dimension so for multiple dimensions we have to use it in
combination with the TD_PRODUCT_DISTRIBUTION action as shown in the following example where we have a
uniform distribution for argument 1 and and an exponential distribution for argument 2
BEGIN_PLUMED_FILE
td_uni: TD_UNIFORM
td_exp: TD_EXPONENTIAL
MINIMUM=-10.0
LAMBDA=0.5
td_pd: TD_PRODUCT_DISTRIBUTION DISTRIBUTIONS=td_uni,td_exp
8.6.3.6
TD_GAUSSIAN
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
563
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Target distribution given by a sum of Gaussian kernels (static).
Employ a target distribution that is given by a sum of multivariate Gaussian (or normal) distributions, defined as
p(s) =
X
wi N (s; µi , Σi )
i
where µi = (µ1,i , µ2,i , . . . , µd,iP
) and Σi are the center and the covariance matrix for the i-th Gaussian. The
weights wi are normalized to 1, i wi = 1.
By default the Gaussian distributions are considered as separable into independent one-dimensional Gaussian
2
2
2
distributions. In other words, the covariance matrix is taken as diagonal Σi = (σ1,i
, σ2,i
, . . . , σd,i
). The Gaussian
distribution is then written as
N (s; µi , σi ) =
d
Y
1
q
k
2
2πσd,i
(sd − µd,i )2
exp −
2
2σd,i
!
where σi = (σ1,i , σ2,i , . . . , σd,i ) is the standard deviation. In this case you need to specify the centers µi using
the numbered CENTER keywords and the standard deviations σi using the numbered SIGMA keywords.
For two arguments it is possible to employ bivariate Gaussian kernels with correlation between arguments, defined as
N (s; µi , σi , ρi ) =
1
p
2πσ1,i σ2,i
"
#!
1
(s1 − µ1,i )2
(s2 − µ2,i )2
2ρi (s1 − µ1,i )(s2 − µ2,i )
exp −
+
−
2
2
2(1 − ρ2i )
σ1,i
σ2,i
σ1,i σ2,i
1 − ρ2i
where ρi is the correlation between s1 and s2 that goes from -1 to 1. In this case the covariance matrix is given as
Σ=
2
σ1,i
ρi σ1,i σ2,i
ρi σ1,i σ2,i
2
σ2,i
The correlation ρ is given using the numbered CORRELATION keywords. A value of ρ = 0 means that the
arguments are considered as un-correlated, which is the default behavior.
The Gaussian distributions are always defined with the conventional normalization factor such that they are normalized to 1 over an unbounded region. However, in calculation within VES we normally consider bounded region on
which the target distribution is defined. Thus, if the center of a Gaussian is close to the boundary of the region it
can happen that the tails go outside the region. In that case it might be needed to use the NORMALIZE keyword
to make sure that the target distribution is properly normalized to 1 over the bounded region. The code will issue a
warning if that is needed.
For periodic CVs it is generally better to use Von Mises distributions instead of Gaussian kernels as these distributions properly account for the periodicity of the CVs.
Options
Generated by Doxygen
564
Additional Modules
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
NORMALIZE
( default=off ) Renormalized the target distribution over the intervals on which
it is defined to make sure that it is properly normalized to 1. In most cases this
should not be needed as the target distributions should be normalized. The
code will issue a warning (but still run) if this is needed for some reason.
CENTER
The centers of the Gaussian distributions. You can use multiple instances of
this keyword i.e. CENTER1, CENTER2, CENTER3...
SIGMA
The standard deviations of the Gaussian distributions. You can use multiple
instances of this keyword i.e. SIGMA1, SIGMA2, SIGMA3...
CORRELATION
The correlation for two-dimensional bivariate Gaussian distributions. Only
works for two arguments. The value should be between -1 and 1. If no value
is given the Gaussian kernels is considered as un-correlated (i.e. value of 0.0).
You can use multiple instances of this keyword i.e. CORRELATION1, CORR←ELATION2, CORRELATION3...
WEIGHTS
The weights of the Gaussian distributions. Have to be as many as the number
of centers given with the numbered CENTER keywords. If no weights are given
the distributions are weighted equally. The weights are automatically normalized to 1.
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
WELLTEMPERED_FACTOR
Examples
One single Gaussian kernel in one-dimension.
BEGIN_PLUMED_FILE
td: TD_GAUSSIAN CENTER1=-1.5 SIGMA1=0.8
Sum of three Gaussian kernels in two-dimensions with equal weights as no weights are given.
BEGIN_PLUMED_FILE
TD_GAUSSIAN ...
CENTER1=-1.5,+1.5 SIGMA1=0.8,0.3
CENTER2=+1.5,-1.5 SIGMA2=0.3,0.8
CENTER3=+1.5,+1.5 SIGMA3=0.4,0.4
LABEL=td
... TD_GAUSSIAN
Sum of three Gaussian kernels in two-dimensions which are weighted unequally. Note that weights are automatically
normalized to 1 so that WEIGHTS=1.0,2.0,1.0 is equal to specifying WEIGHTS=0.25,0.50,0.25.
BEGIN_PLUMED_FILE
TD_GAUSSIAN ...
CENTER1=-1.5,+1.5 SIGMA1=0.8,0.3
CENTER2=+1.5,-1.5 SIGMA2=0.3,0.8
CENTER3=+1.5,+1.5 SIGMA3=0.4,0.4
WEIGHTS=1.0,2.0,1.0
LABEL=td
... TD_GAUSSIAN
Sum of two bivariate Gaussian kernels where there is correlation of ρ2 = 0.75 between the two arguments for the
second Gaussian.
BEGIN_PLUMED_FILE
TD_GAUSSIAN ...
CENTER1=-1.5,+1.5 SIGMA1=0.8,0.3
CENTER2=+1.5,-1.5 SIGMA2=0.3,0.8 CORRELATION2=0.75
LABEL=td
... TD_GAUSSIAN
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
8.6.3.7
565
TD_GENERALIZED_EXTREME_VALUE
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Generalized extreme value distribution (static).
Employ a target distribution given by a generalized extreme value distribution that is defined as
p(s) =
where
t(s) = { (1 + ξ
s−µ
σ
1
t(s)ξ+1 e−t(s) ,
σ
−1/ξ
s−µ
if ξ 6= 0 exp −
if ξ = 0
σ
, and µ is the location parameter which approximately determines the location of the maximum of the distribution,
σ > 0 is the scale parameter that determines the broadness of the distribution, and ξ is the shape parameter that
determines the tail behavior of the distribution. For ξ = 0, ξ > 0, and ξ < 0 the Gumbel, Frechet, and Weibull
families of distributions are obtained, respectively.
The location parameter µ is given using the LOCATION keyword, the scale parameter σ using the SCALE keyword,
and the shape parameter ξ using the SHAPE keyword.
This target distribution action is only defined for one dimension, for multiple dimensions it should be used in combination with TD_PRODUCT_DISTRIBUTION action.
Compulsory keywords
LOCATION
The µ parameter of the generalized extreme value distribution.
SCALE
The σ parameter for the generalized extreme value distribution given as a positive number.
SHAPE
The ξ parameter for the generalized extreme value distribution.
Options
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
NORMALIZE
( default=off ) Renormalized the target distribution over the intervals on which
it is defined to make sure that it is properly normalized to 1. In most cases this
should not be needed as the target distributions should be normalized. The
code will issue a warning (but still run) if this is needed for some reason.
WELLTEMPERED_FACTOR
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
Examples
Generated by Doxygen
566
Additional Modules
Generalized extreme value distribution with µ = 0.0, σ = 2.0, and ξ = 0.0 (Gumbel distribution)
BEGIN_PLUMED_FILE
td: TD_GENERALIZED_EXTREME_VALUE
LOCATION=0.0
SCALE=2.0 SHAPE=0.0
Generalized extreme value distribution with µ = −5.0, σ = 1.0, and ξ = 0.5 (Frechet distribution)
BEGIN_PLUMED_FILE
td: TD_GENERALIZED_EXTREME_VALUE
LOCATION=-5.0
SCALE=1.0 SHAPE=0.5
Generalized extreme value distribution with µ = 5.0, σ = 2.0, and ξ = −0.5 (Weibull distribution)
BEGIN_PLUMED_FILE
td: TD_GENERALIZED_EXTREME_VALUE
LOCATION=5.0
SCALE=1.0 SHAPE=-0.5
The generalized extreme value distribution is only defined for one dimension so for multiple dimensions we have to
use it in combination with the TD_PRODUCT_DISTRIBUTION action as shown in the following example where we
have a Generalized extreme value distribution for argument 1 and uniform distribution for argument 2
BEGIN_PLUMED_FILE
td_gev: TD_GENERALIZED_EXTREME_VALUE
LOCATION=-5.0
SCALE=1.0 SHAPE=0.5
td_uni: TD_UNIFORM
td_pd: TD_PRODUCT_DISTRIBUTION DISTRIBUTIONS=td_gev,td_uni
8.6.3.8
TD_GENERALIZED_NORMAL
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Target distribution given by a sum of generalized normal distributions (static).
Employ a target distribution that is given by a sum where each term is a product of one-dimensional generalized
normal distributions (version 1, also know as an exponential power distribution), defined as
!
d
β
X
Y
βk,i
sk − µk,i k,i
p(s) =
wi
exp −
2 αk,i Γ(1/βk,i )
αk,i
i
k
where (µ1,i , µ2,i , . . . , µd,i ) are the centers of the distributions, (α1,i , α2,i , . . . , αd,i ) are the scale parameters of the
distributions, (β1,i , β2,i , . . . , βd,i ) arePthe shape parameters of the distributions, and Γ(x) is the gamma function.
The weights wi are normalized to 1, i wi = 1.
Employing β = 2 results in a Gaussian (normal) distributions with mean µ and variance α2 /2, β = 1 gives the
Laplace distribution, and the limit β → ∞ results in a uniform distribution on the interval [µ − α, µ + α].
The centers (µ1,i , µ2,i , . . . , µd,i ) are given using the numbered CENTER keywords, the scale parameters
(α1,i , α2,i , . . . , αd,i ) using the numbered SCALE keywords, and the shape parameters (β1,i , β2,i , . . . , βd,i ) using the numbered SHAPE keywords. The weights are given using the WEIGHTS keywords, if no weights are given
are all terms weighted equally.
Options
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
567
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
NORMALIZE
( default=off ) Renormalized the target distribution over the intervals on which
it is defined to make sure that it is properly normalized to 1. In most cases this
should not be needed as the target distributions should be normalized. The
code will issue a warning (but still run) if this is needed for some reason.
CENTER
The center of each generalized normal distribution. You can use multiple instances of this keyword i.e. CENTER1, CENTER2, CENTER3...
ALPHA
The alpha parameters for each generalized normal distribution. You can use
multiple instances of this keyword i.e. ALPHA1, ALPHA2, ALPHA3...
BETA
The beta parameters for each generalized normal distribution. You can use
multiple instances of this keyword i.e. BETA1, BETA2, BETA3...
WEIGHTS
The weights of the generalized normal distribution. By default all are weighted
equally.
WELLTEMPERED_FACTOR
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
Examples
A generalized normal distribution in one-dimensional
BEGIN_PLUMED_FILE
td1: TD_GENERALIZED_NORMAL CENTER1=+20.0
ALPHA1=5.0
BETA1=4.0
A sum of two one-dimensional generalized normal distributions
BEGIN_PLUMED_FILE
TD_GENERALIZED_NORMAL ...
CENTER1=+20.0 ALPHA1=5.0
CENTER2=-20.0 ALPHA2=5.0
LABEL=td1
... TD_GENERALIZED_NORMAL
BETA1=4.0
BETA2=3.0
A sum of two two-dimensional generalized normal distributions
BEGIN_PLUMED_FILE
TD_GENERALIZED_NORMAL ...
CENTER1=-20.0,-20.0 ALPHA1=5.0,3.0 BETA1=2.0,4.0
CENTER2=-20.0,+20.0 ALPHA2=3.0,5.0 BETA2=4.0,2.0
WEIGHTS=2.0,1.0
LABEL=td1
... TD_GENERALIZED_NORMAL
8.6.3.9
TD_GRID
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Generated by Doxygen
568
Additional Modules
Target distribution from an external grid file (static).
Using this keyword you can use a target distribution that is read from an external grid file that is in the proper PLU←MED file format. You do not to give any information about the external grid file as all relevant information should be
automatically detected. It is assumed that the distribution read in from the grid is a proper probability distribution,
i.e. always non-negative and can be normalized.
By default the target distribution from the external grid is always normalized inside the code. You can disable this
normalization by using DO_NOT_NORMALIZE keyword. However, be warned that this will generally lead to the
wrong behavior if the distribution from the external grid is not properly normalized to 1.
If the distribution from the external grid file has for some reason negative values can you use the SHIFT keyword to
shift the distribution by a given value. Another option is to use the SHIFT_TO_ZERO keyword to shift the minimum
of the distribution to zero.
Note that the number of grid bins used in the external grid file do not have to be the same as used in the bias or
action where the target distribution is employed as the code will employ a linear (or bilinear for two dimensions)
interpolation to calculate values. Currently only one or two dimensional grids are supported.
It can happen that the intervals on which the target distribution is defined is larger than the intervals covered by the
external grid file. In this case the default option is to consider the target distribution as continuous such that values
outside the boundary of the external grid file are the same as at the boundary. This can be changed by using the
ZERO_OUTSIDE keyword which will make values outside to be taken as zero.
Compulsory keywords
FILE
The name of the external grid file to be used as a target distribution.
Options
ZERO_OUTSIDE
DO_NOT_NORMALIZE
( default=off ) By default the target distribution is continuous such that values
outside the boundary of the external grid file are the same as at the boundary.
This can be changed by using this flag which will make values outside to be
taken as zero.
( default=off ) By default the target distribution from the external grid is always
normalized inside the code. You can use this flag to disable this normalization.
However, be warned that this will generally lead to the wrong behavior if the
distribution from the external grid is not properly normalized to 1.
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
SHIFT
Shift the grid read in by some constant value. Due to normalization the final
shift in the target distribution will generally not be the same as the value given
here
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
WELLTEMPERED_FACTOR
Examples
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
569
Generally you only need to provide the the filename of the external grid file.
BEGIN_PLUMED_FILE
td: TD_GRID FILE=input-grid.data
8.6.3.10
TD_LINEAR_COMBINATION
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Target distribution given by linear combination of distributions (static or dynamic).
Employ a target distribution that is a linear combination of the other distributions, defined as
p(s) =
X
wi pi (s)
i
where the weights wi are normalized to 1,
P
i
wi = 1.
The labels of the distributions pi (s) to be used in the linear combination are given in the DISTRIBUTIONS keyword.
The weights wi can be given using the WEIGHTS keyword. The distributions are weighted equally if no weights are
given.
It is assumed that all the distributions pi (s) are normalized. If that is not the case for some reason should you
normalize each distribution separately by using the NORMALIZE keyword when defining them in the input file (i.e.
before the TD_LINEAR_COMBINATION action). Note that normalizing the overall linear combination will generally
lead to different results than normalizing each distribution separately.
The linear combination will be a dynamic target distribution if one or more of the distributions used is a dynamic
distribution, otherwise it will be a static distribution.
Compulsory keywords
DISTRIBUTIONS
The labels of the target distribution actions to be used in the linear combination.
Options
NORMALIZE
( default=off ) Renormalized the target distribution over the intervals on which
it is defined to make sure that it is properly normalized to 1. In most cases this
should not be needed as the target distributions should be normalized. The
code will issue a warning (but still run) if this is needed for some reason.
WEIGHTS
The weights of target distributions. Have to be as many as the number of target
distribution labels given in DISTRIBUTIONS. If no weights are given the distributions are weighted equally. The weights are automatically normalized to
1.
Generated by Doxygen
570
Additional Modules
WELLTEMPERED_FACTOR
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
Examples
Here we employ a linear combination of a uniform and a Gaussian distribution. No weights are given so the two
distributions will be weighted equally.
BEGIN_PLUMED_FILE
td_uni: TD_UNIFORM
td_gauss: TD_GAUSSIAN CENTER1=-2.0 SIGMA1=0.5
td_comb: TD_LINEAR_COMBINATION DISTRIBUTIONS=td_uniform,td_gaussian
Here we employ a linear combination of a uniform and two Gaussian distribution. The weights are automatically
normalized to 1 such that giving WEIGHTS=1.0,1.0,2.0 as we do here is equal to giving WEIGHTS=0.25,0.25,0.50.
BEGIN_PLUMED_FILE
td_uni: TD_UNIFORM
td_gauss1: TD_GAUSSIAN CENTER1=-2.0,-2.0 SIGMA1=0.5,0.3
td_gauss2: TD_GAUSSIAN CENTER1=+2.0,+2.0 SIGMA1=0.3,0.5
TD_LINEAR_COMBINATION ...
DISTRIBUTIONS=td_uni,td_gauss1,td_gauss2
WEIGHTS=1.0,1.0,2.0
LABEL=td_comb
... TD_LINEAR_COMBINATION
In the above example the two Gaussian kernels are given using two separate DISTRIBUTION keywords. As the
TD_GAUSSIAN target distribution allows multiple centers is it also possible to use just one DISTRIBUTION keyword
for the two Gaussian kernels. This is shown in the following example which will give the exact same result as the
one above as the weights have been appropriately adjusted
BEGIN_PLUMED_FILE
td_uni: TD_UNIFORM
TD_GAUSSIAN ...
CENTER1=-2.0,-2.0
CENTER2=+2.0,+2.0
WEIGHTS=1.0,2.0
LABEL=td_gauss
... TD_GAUSSIAN
SIGMA1=0.5,0.3
SIGMA2=0.3,0.5
TD_LINEAR_COMBINATION ...
DISTRIBUTIONS=td_uni,td_gauss
WEIGHTS=0.25,0.75
LABEL=td_comb
... TD_LINEAR_COMBINATION
8.6.3.11
TD_MARGINAL_WELLTEMPERED
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
571
One-dimensional marginal well-tempered target distribution (dynamic).
One-dimensional marginal well-tempered distribution [47] given by
p(sk ) = R
[P0 (sk )]1/γ
e−(β/γ)F (sk )
R
=
dsk e−(β/γ)F (sk )
dsk [P0 (sk )]1/γ
where γ is a so-called bias factor and P0 (s) is the unbiased canonical distribution of the CVs. This target distribution
thus correponds to a biased ensemble where, as compared to the unbiased one, the probability peaks have been
broaden and the fluctations of the CVs are enhanced. The value of the bias factor γ determines by how much the
fluctations are enhanced.
Compulsory keywords
BIASFACTOR
The bias factor to be used for the well tempered distribution
MARGINAL_ARG
The argument to be used for the marginal.
Examples
8.6.3.12
TD_PRODUCT_COMBINATION
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Target distribution given by product combination of distributions (static or dynamic).
Employ a target distribution that is a product combination of the other distributions, defined as
Q
p(s) = R
ds
pi (s)
iQ
i
pi (s)
where the distributions pi (s) are in full dimensional space of the arguments used.
Note the difference between this target distribution and the one defined in TD_PRODUCT_DISTRIBUTION. Here
we have a non-separable distribution given as a product of distribution pi (s) which are in full dimensional space of
the arguments used.
The labels of the distributions pi (s) to be used in the product combination are given in the DISTRIBUTIONS keyword.
The target distribution resulting from the product combination will be automatically normalized. Therefore, the
product combination needs to be a proper distribution that is non-negative and that can be normalized. The code
will perform checks to make sure that this is indeed the case.
The product combination will be a dynamic target distribution if one or more of the distributions used is a dynamic
distribution. Otherwise it will be a static distribution.
Compulsory keywords
Generated by Doxygen
572
Additional Modules
DISTRIBUTIONS
The labels of the target distribution actions to be used in the product combination.
Options
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
WELLTEMPERED_FACTOR
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
Examples
In the following example the overall interval on which the target distribution is defined is from 0.23 to 0.8. We
employ a product combination of a well-tempered distribution and a uniform distribution that decays to zero at 0.6.
This results in a target distribution that is well-tempered from 0.23 to 0.6 and then decays to zero. In other words,
we cut off the tail of the well-tempered distribution at 0.6
BEGIN_PLUMED_FILE
td_welltemp: TD_WELLTEMPERED BIASFACTOR=5
td_uniform: TD_UNIFORM MINIMA=0.23 MAXIMA=0.6 SIGMA_MAXIMA=0.05
td_combination: TD_PRODUCT_COMBINATION DISTRIBUTIONS=td_uniform,td_welltemp
In the following example the overall interval on which the target distribution is defined is from -4 to 4. We employ a
product of a Gaussian distribution with two centers and distribution that is uniform on the interval -3 to 3 and then
smoothly decays to zero outside that interval. The overall effect will then be to cut off the tails of the Gaussian
distribution
BEGIN_PLUMED_FILE
TD_GAUSSIAN ...
CENTER1=-2.9 SIGMA1=1.0
CENTER2=+2.9 SIGMA2=0.4
LABEL=td_gauss
... TD_GAUSSIAN
TD_UNIFORM ...
MINIMA=-3.0 SIGMA_MINIMA=0.20
MAXIMA=+3.0 SIGMA_MAXIMA=0.15
LABEL=td_uni
... TD_UNIFORM
td_pc: TD_PRODUCT_COMBINATION DISTRIBUTIONS=td_gauss,td_uni
8.6.3.13
TD_PRODUCT_DISTRIBUTION
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Target distribution given by a separable product of one-dimensional distributions (static or dynamic).
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
573
Employ a target distribution that is a separable product of one-dimensional distributions, defined as
p(s) =
d
Y
pk (sk )
k
where d is the number of arguments used and pk (sk ) is the one-dimensional distribution corresponding to the k -th
argument.
Note the difference between this target distribution and the one defined in TD_PRODUCT_COMBINATION. Here
we have a separable distribution given as a product of one-dimensional distribution pk (sk ).
The labels of the one-dimensional distributions pk (sk ) to be used in the product distribution are given in the DIS←TRIBUTIONS keyword. Note that the order of the labels is very important.
It is assumed that all the distributions to be used in the product distribution are normalized. If that is not the case
you need to normalize the distributions by using the NORMALIZE keyword. Here it does not matter if you normalize
each distribution separately or the overall product, it will give the same results.
The product distribution will be a dynamic target distribution if one or more of the distributions used is a dynamic
distribution. Otherwise it will be a static distribution.
Compulsory keywords
DISTRIBUTIONS
Labels of the one-dimensional target distribution actions for each argument to be used in
the product distribution. Note that order of the labels is important.
Options
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
NORMALIZE
( default=off ) Renormalized the target distribution over the intervals on which
it is defined to make sure that it is properly normalized to 1. In most cases this
should not be needed as the target distributions should be normalized. The
code will issue a warning (but still run) if this is needed for some reason.
WELLTEMPERED_FACTOR
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
Examples
In the following example we employ a uniform distribution for argument 1 and a Gaussian distribution for argument
2.
BEGIN_PLUMED_FILE
target_uniform: TD_UNIFORM
target_Gaussian: TD_GAUSSIAN CENTER=-2.0 SIGMA=0.5
td_pd: TD_PRODUCT_DISTRIBUTION DISTRIBUTIONS=target_uniform,target_Gaussian
Generated by Doxygen
574
Additional Modules
Note that order of the labels is important, using DISTRIBUTIONS=target_Gaussian,target_uniform would mean that
we would employ a Gaussian distribution for argument 1 and a uniform distribution for argument 2, which would lead
to completely different results.
8.6.3.14
TD_UNIFORM
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Uniform target distribution (static).
Using this keyword you can define a uniform target distribution which is a product of one-dimensional distributions
pk (sk ) that are uniform over a given interval [ak , bk ]
pk (sk ) = { 1(bk − ak )if ak ≤ sk ≤ bk 0otherwise
The overall distribution is then given as
p(s) =
d
Y
pk (sk ) = {
Qd
k
k
1
if ak ≤ sk ≤ bk for all k0otherwise
(bk − ak )
The distribution is thus uniform inside a rectangular for two arguments and a cube for a three arguments.
The limits of the intervals ak and bk are given with the MINIMA and MAXIMA keywords, respectively. If one or both
of these keywords are missing the code should automatically detect the limits.
It is also possible to use one-dimensional distributions that go smoothly to zero at the boundaries. This is done by
employing a function with Gaussian switching functions at the boundaries ak and bk
fk (sk ) = { exp
(sk − ak )2
−
2
2σa,k
!
(sk − bk )2
if sk < ak 1if ak ≤ sk ≤ bk exp −
2
2σb,k
!
if sk > bk
where the standard deviation parameters σa,k and σb,k determine how quickly the switching functions goes to zero.
The overall distribution is then normalized
p(s) =
d
Y
k
pk (sk ) =
d
Y
R
k
f (sk )
dsk f (sk )
To use this option you need to provide the standard deviation parameters σa,k and σb,k by using the SIGMA_MI←NIMA and SIGMA_MAXIMA keywords, respectively. Giving a value of 0.0 means that the boundary is sharp, which
is the default behavior.
Options
MINIMA
The minima of the intervals where the target distribution is taken as uniform. You should
give one value for each argument.
MAXIMA
The maxima of the intervals where the target distribution is taken as uniform. You should
give one value for each argument.
SIGMA_MINIMA
The standard deviation parameters of the Gaussian switching functions for the minima of
the intervals. You should give one value for each argument. Value of 0.0 means that switch
is done without a smooth switching function, this is the default behavior.
SIGMA_MAXIMA
by Doxygen
The standard deviation parameters of the Gaussian switching functions forGenerated
the maxima
of
the intervals. You should give one value for each argument. Value of 0.0 means that switch
is done without a smooth switching function, this is the default behavior.
8.6 Variationally Enhanced Sampling (VES code)
575
Examples
If one or both of the MINIMA or MAXIMA keywords are missing the code should automatically detect the limits not
given. Therefore, if we consider a target distribution that is defined over an interval from 0.0 to 10.0 for the first
argument and from 0.2 to 1.0 for the second argument are all of the following examples equivalent
BEGIN_PLUMED_FILE
td: TD_UNIFORM
BEGIN_PLUMED_FILE
TD_UNIFORM ...
MINIMA=0.0,0,2
MAXIMA=10.0,1.0
LABEL=td
... TD_UNIFORM
BEGIN_PLUMED_FILE
td: TD_UNIFORM MAXIMA=10.0,1.0
BEGIN_PLUMED_FILE
td: TD_UNIFORM MINIMA=0.0,0,2
We can also define a target distribution that goes smoothly to zero at the boundaries of the uniform distribution. In
the following we consider an interval of 0 to 10 for the target distribution. The following input would result in a target
distribution that would be uniform from 2 to 7 and then smoothly go to zero from 2 to 0 and from 7 to 10.
BEGIN_PLUMED_FILE
TD_UNIFORM ...
MINIMA=2.0
MAXIMA=+7.0
SIGMA_MINIMA=0.5
SIGMA_MAXIMA=1.0
LABEL=td
... TD_UNIFORM
It is also possible to employ a smooth switching function for just one of the boundaries as shown here where the
target distribution would be uniform from 0 to 7 and then smoothly go to zero from 7 to 10.
BEGIN_PLUMED_FILE
TD_UNIFORM ...
MAXIMA=+7.0
SIGMA_MAXIMA=1.0
LABEL=td
... TD_UNIFORM
Furthermore, it is possible to employ a sharp boundary by using
BEGIN_PLUMED_FILE
TD_UNIFORM ...
MAXIMA=+7.0
SIGMA_MAXIMA=0.0
LABEL=td
... TD_UNIFORM
or
BEGIN_PLUMED_FILE
td: TD_UNIFORM MAXIMA=+7.0
8.6.3.15
TD_VONMISES
Generated by Doxygen
576
Additional Modules
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Target distribution given by a sum of Von Mises distributions (static).
Employ a target distribution that is given by a sum where each term is a product of one-dimensional Von Mises
distributions,
p(s) =
X
i
wi
d
Y
exp (κk,i cos(sk − µk,i ))
2πI0 (κk,i )
k
where (µ1,i , µ2,i , . . . , µd,i ) are the centers of the distributions, (κ1,i , κ2,i , . . . , κd,i ) are parameters that determine
the extend
P of each distribution, and I0 (x) is the modified Bessel function of order 0. The weights wi are normalized
to 1, i wi = 1.
The Von Mises distribution isp
defined for periodic variables with a periodicity of 2π and is analogous to the Gaussian
distribution. The parameter 1/κ is comparable to the standard deviation σ for the Gaussian distribution.
To use this target distribution you need to give the centers (µ1,i , µ2,i , . . . , µd,i ) by using the numbered CENTER
p
p
p
keywords and the "standard deviations" ( 1/κ1,i , 1/κ2,i , . . . , 1/κd,i ) using the numbered SIGMA keywords.
Options
SHIFT_TO_ZERO
( default=off ) Shift the minimum value of the target distribution to zero. This
can for example be used to avoid negative values in the target distribution. If
this option is active the distribution will be automatically normalized.
CENTER
The centers of the Von Mises distributions. You can use multiple instances of
this keyword i.e. CENTER1, CENTER2, CENTER3...
SIGMA
The "standard deviations" of the Von Mises distributions. You can use multiple
instances of this keyword i.e. SIGMA1, SIGMA2, SIGMA3...
WEIGHTS
The weights of the Von Mises distributions. Have to be as many as the number
of centers given with the numbered CENTER keywords. If no weights are given
the distributions are weighted equally. The weights are automatically normalized to 1.
Broaden the target distribution such that it is taken as [p(s)]∧ (1/ γ ) where γ is
the well tempered factor given here. If this option is active the distribution will
be automatically normalized.
WELLTEMPERED_FACTOR
Examples
Sum of two Von Mises distribution in one dimension that have equal weights as no weights are given.
BEGIN_PLUMED_FILE
TD_VONMISES ...
CENTER1=+2.0 SIGMA1=0.6
CENTER2=-2.0 SIGMA2=0.7
LABEL=td
... TD_VONMISES
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
577
Sum of two Von Mises distribution in two dimensions that have different weights. Note that the weights are automatically normalized to 1 such that specifying WEIGHTS=1.0,2.0 is equal to specifying WEIGHTS=0.33333,0.66667.
BEGIN_PLUMED_FILE
TD_VONMISES ...
CENTER1=+2.0,+2.0 SIGMA1=0.6,0.7
CENTER2=-2.0,+2.0 SIGMA2=0.7,0.6
WEIGHTS=1.0,2.0
LABEL=td
... TD_VONMISES
8.6.3.16
TD_WELLTEMPERED
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Well-tempered target distribution (dynamic).
Use as a target distribution the well-tempered distribution [47] given by
p(s) = R
e−(β/γ)F (s)
[P (s)]1/γ
R 0
=
ds e−(β/γ)F (s)
ds [P0 (s)]1/γ
where γ is a so-called bias factor and P0 (s) is the unbiased canonical distribution of the CVs. This target distribution
thus corresponds to a biased ensemble where, as compared to the unbiased one, the probability peaks have been
broaden and the fluctuations of the CVs are enhanced. The value of the bias factor γ determines by how much the
fluctuations are enhanced.
The well-tempered distribution can be view as sampling on an effective free energy surface F̃ (s) = (1/γ)F (s)
which has largely the same metastable states as the original F (s) but with barriers that have been reduced by a
factor of γ . Generally one should use a value of γ that results in effective barriers on the order of few kB T such that
thermal fluctuations can easily induce transitions between different metastable states.
At convergence the relationship between the bias potential and the free energy surface is given by
F (s) = −
1
1 − γ −1
V (s)
This target distribution depends directly on the free energy surface F (s) which is quantity that we do not know
a-priori and want to obtain. Therefore, this target distribution is iteratively updated [87] according to
(m+1)
p(m+1) (s) = R
(s)
e−(β/γ)F
(m+1) (s)
−(β/γ)F
ds e
where F (m+1) (s) is the current best estimate of the free energy surface obtained according to
F (m+1) (s) = −V (m+1) (s) −
1
1
log p(m) (s) = −V (m+1) (s) + F (m) (s)
β
γ
The frequency of performing this update needs to be set in the optimizer used in the calculation. Normally it is
sufficient to do it every 100-1000 bias update iterations.
Compulsory keywords
Generated by Doxygen
578
Additional Modules
BIASFACTOR
The bias factor used for the well-tempered distribution.
Examples
Employ a well-tempered target distribution with a bias factor of 10
BEGIN_PLUMED_FILE
td_welltemp: TD_WELLTEMPERED BIASFACTOR=10
8.6.4
Optimizers
The following list contains the optimizers available in the VES code.
8.6.4.1
OPT_AVERAGED_SGD
Averaged stochastic gradient decent with fixed step size.
OPT_DUMMY
Dummy optimizer for debugging.
OPT_ROBBINS_MONRO_SGD
Robbins-Monro stochastic gradient decent.
OPT_STEEPEST_DECENT
Steepest decent optimizer.
OPT_AVERAGED_SGD
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Averaged stochastic gradient decent with fixed step size.
Algorithm
This optimizer updates the coefficients according to the averaged stochastic gradient decent algorithm described in
ref [88]. This algorithm considers two sets of coefficients, the so-called instantaneous coefficients that are updated
according to the recursion formula given by
h
i
α(n+1) = α(n) − µ ∇Ω(ᾱ(n) ) + H(ᾱ(n) )[α(n) − ᾱ(n) ] ,
where µ is a fixed step size and the gradient ∇Ω(ᾱ(n) ) and the Hessian H(ᾱ(n) ) depend on the averaged coefficients defined as
n
ᾱ(n) =
1 X (k)
α .
n+1
k=0
This means that the bias acting on the system depends on the averaged coefficients ᾱ(n) which leads to a smooth
convergence of the bias and the estimated free energy surface. Furthermore, this allows for a rather short sampling
time for each iteration, for classical MD simulations typical sampling times are on the order of few ps (around
1000-4000 MD steps).
Currently it is only supported to employ the diagonal part of the Hessian which is generally sufficient. Support for
employing the full Hessian will be added later on.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
579
The VES bias that is to be optimized should be specified using the BIAS keyword. The fixed step size µ is given
using the STEPSIZE keyword. The frequency of updating the coefficients is given using the STRIDE keyword where
the value is given in the number of MD steps. For example, if the MD time step is 0.02 ps and STRIDE=2000 will
the coefficients be updated every 4 ps. The coefficients will be outputted to the file given by the COEFFS_FILE
keyword. How often the coefficients are written to this file is controlled by the COEFFS_OUTPUT keyword.
If the VES bias employs a dynamic target distribution that needs to be iteratively updated (e.g. TD_WELLTEMPERED)
[87], you will need to specify the stride for updating the target distribution by using the TARGETDIST_STRIDE
keyword where the stride is given in terms coefficient iterations. For example if the MD time step is 0.02 ps and
STRIDE=1000, such that the coefficients are updated every 2 ps, will TARGETDIST_STRIDE=500 mean that the
target distribution will be updated every 1000 ps.
The output of the free energy surfaces and biases is controlled by the FES_OUTPUT and the BIAS_OUTPUT
keywords. It is also possible to output one-dimensional projections of the free energy surfaces by using the FES←_PROJ_OUTPUT keyword but for that to work you will need to select for which argument to do the projections by
using the numbered PROJ_ARG keyword in the VES bias that is optimized. You can also output dynamic target
distributions by using the TARGETDIST_OUTPUT and TARGETDIST_PROJ_OUTPUT keywords.
It is possible to start the optimization from some initial set of coefficients that have been previously obtained by
using the INITIAL_COEFFS keyword.
When restarting simulations it should be sufficient to put the RESTART action in the beginning of the input files (or
some MD codes the PLUMED should automatically detect if it is a restart run) and keep the same input as before
The restarting of the optimization should be automatic as the optimizer will then read in the coefficients from the file
given in COEFFS_FILE. For dynamic target distribution the code will also read in the final target distribution from
the previous run (which is always outputted even if the TARGETDIST_OUTPUT keyword is not used).
This optimizer supports the usage of multiple walkers where different copies of the system share the same bias
potential (i.e. coefficients) and cooperatively sample the averages needed for the gradient and Hessian. This can
significantly help with convergence in difficult cases. It is of course best to start the different copies from different
positions in CV space. To activate this option you just need to add the MULTIPLE_WALKERS flag. Note that this is
only supported if the MD code support running multiple replicas connected via MPI.
The optimizer supports the usage of a so-called mask file that can be used to employ different step sizes for different
coefficients and/or deactivate the optimization of certain coefficients (by putting values of 0.0). The mask file is read
in by using the MASK_FILE keyword and should be in the same format as the coefficient file. It is possible to
generate a template mask file by using the OUTPUT_MASK_FILE keyword.
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Quantity
Keyword
Description
gradrms
MONITOR_INSTANTANEOUS_GRADIENT
the root mean square value of the coefficient
gradient. For multiple biases this component
is labeled using the number of the bias as
gradrms-#.
gradmax
MONITOR_INSTANTANEOUS_GRADIENT
the largest absolute value of the coefficient
gradient. For multiple biases this component
is labeled using the number of the bias as
gradmax-#.
avergradrms
MONITOR_AVERAGE_GRADIENT
the root mean square value of the averaged
coefficient gradient. For multiple biases this
component is labeled using the number of the
bias as gradrms-#.
MONITOR_AVERAGE_GRADIENT
the largest absolute value of the averaged
coefficient gradient. For multiple biases this
component is labeled using the number of the
bias as gradmax-#.
Generated by Doxygen
avergradmax
580
Additional Modules
Compulsory keywords
BIAS
the label of the VES bias to be optimized
STRIDE
the frequency of updating the coefficients given in the number of MD steps.
COEFFS_FILE
( default=coeffs.data ) the name of output file for the coefficients
COEFFS_OUTPUT
( default=100 ) how often the coefficients should be written to file. This parameter is given
as the number of iterations.
the step size used for the optimization
STEPSIZE
Options
MONITOR_INSTANTANEOUS_GRADIENT
( default=off ) if quantities related to the instantaneous
gradient should be outputted.
MULTIPLE_WALKERS
( default=off ) if optimization is to be performed using
multiple walkers connected via MPI
START_OPTIMIZATION_AFRESH
( default=off ) if the iterations should be started afresh
when a restart has been triggered by the RESTART
keyword or the MD code.
MONITOR_AVERAGE_GRADIENT
( default=off ) if the averaged gradient should be monitored and quantities related to it should be outputted.
COEFFS_FMT
specify format for coefficient file(s) (useful for decrease
the number of digits in regtests)
COEFFS_SET_ID_PREFIX
suffix to add to the filename given in FILE to identify
the bias, should only be given if a single filename is
given in FILE when optimizing multiple biases.
INITIAL_COEFFS
the name(s) of file(s) with the initial coefficients
TARGETDIST_AVERAGES_FILE
the name of output file for the target distribution averages. By default it is targetdist-averages.data.
TARGETDIST_AVERAGES_OUTPUT
how often the target distribution averages should be
written out to file. Note that the value is given in terms
of coefficient iterations. If no value is given are the averages only written at the beginning of the optimization
BIAS_OUTPUT
how often the bias(es) should be written out to file.
Note that the value is given in terms of coefficient iterations.
how often the FES(s) should be written out to file. Note
that the value is given in terms of coefficient iterations.
FES_OUTPUT
FES_PROJ_OUTPUT
RESTART
how often the projections of the FES(s) should be written out to file. Note that the value is given in terms of
coefficient iterations.
allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM
Only update this action from this time
UPDATE_UNTIL
Only update this action until this time
MASK_FILE
read in a mask file which allows one to employ different step sizes for different coefficients and/or deactivate the optimization of certain coefficients (by putting
values of 0.0). One can write out the resulting mask by
using the OUTPUT_MASK_FILE keyword.
OUTPUT_MASK_FILE
Name of the file to write out the mask resulting from
using the MASK_FILE keyword. Can also be used to
generate a template mask file.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
581
MONITOR_AVERAGES_GRADIENT_EXP_DECAY
use an exponentially decaying averaging with a given
time constant when monitoring the averaged gradient
TARGETDIST_STRIDE
stride for updating a target distribution that is iteratively
updated during the optimization. Note that the value is
given in terms of coefficient iterations.
TARGETDIST_OUTPUT
how often the dynamic target distribution(s) should be
written out to file. Note that the value is given in terms
of coefficient iterations.
how often the projections of the dynamic target distribution(s) should be written out to file. Note that the
value is given in terms of coefficient iterations.
TARGETDIST_PROJ_OUTPUT
EXP_DECAYING_AVER
calculate the averaged coefficients using exponentially
decaying averaging using the decaying constant given
here in the number of iterations
Examples
In the following input we employ an averaged stochastic gradient decent with a fixed step size of 1.0 and update the
coefficient every 1000 MD steps (e.g. every 2 ps if the MD time step is 0.02 ps). The coefficient are outputted to
the coefficients.data every 50 iterations while the FES and bias is outputted to files every 500 iterations (e.g. every
1000 ps).
BEGIN_PLUMED_FILE
phi:
TORSION ATOMS=5,7,9,15
bf1: BF_FOURIER ORDER=5 MINIMUM=-pi MAXIMUM=pi
VES_LINEAR_EXPANSION ...
ARG=phi
BASIS_FUNCTIONS=bf1
LABEL=ves1
TEMP=300.0
GRID_BINS=100
... VES_LINEAR_EXPANSION
OPT_AVERAGED_SGD ...
BIAS=ves1
STRIDE=1000
LABEL=o1
STEPSIZE=1.0
COEFFS_FILE=coefficients.data
COEFFS_OUTPUT=50
FES_OUTPUT=500
BIAS_OUTPUT=500
... OPT_AVERAGED_SGD
In the following example we employ a well-tempered target distribution that is updated every 500 iterations (e.g.
every 1000 ps). The target distribution is also output to a file every 2000 iterations (the TARGETDIST_OUTPUT
keyword). Here we also employ MULTIPLE_WALKERS flag to enable the usage of multiple walkers.
BEGIN_PLUMED_FILE
phi:
TORSION ATOMS=5,7,9,15
psi:
TORSION ATOMS=7,9,15,17
bf1: BF_FOURIER ORDER=5 MINIMUM=-pi MAXIMUM=pi
bf2: BF_FOURIER ORDER=4 MINIMUM=-pi MAXIMUM=pi
td1: TD_WELLTEMPERED BIASFACTOR=10
VES_LINEAR_EXPANSION ...
ARG=phi,psi
Generated by Doxygen
582
Additional Modules
BASIS_FUNCTIONS=bf1,bf2
LABEL=ves1
TEMP=300.0
GRID_BINS=100,100
TARGET_DISTRIBUTION=td1
PROJ_ARG1=phi
PROJ_ARG2=psi
... VES_LINEAR_EXPANSION
OPT_AVERAGED_SGD ...
BIAS=ves1
STRIDE=1000
LABEL=o1
STEPSIZE=1.0
MULTIPLE_WALKERS
COEFFS_FILE=coefficients.data
COEFFS_OUTPUT=50
FES_OUTPUT=500
FES_PROJ_OUTPUT=500
BIAS_OUTPUT=500
TARGETDIST_STRIDE=500
TARGETDIST_OUTPUT=2000
... OPT_AVERAGED_SGD
8.6.4.2
OPT_DUMMY
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Dummy optimizer for debugging.
This is dummy optimizer that can be used for debugging. It will not update the coefficients but can be used to
monitor the gradient and Hessian for a given VES bias.
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Quantity
Keyword
Description
gradrms
MONITOR_INSTANTANEOUS_GRADIENT
the root mean square value of the coefficient
gradient. For multiple biases this component
is labeled using the number of the bias as
gradrms-#.
gradmax
MONITOR_INSTANTANEOUS_GRADIENT
the largest absolute value of the coefficient
gradient. For multiple biases this component
is labeled using the number of the bias as
gradmax-#.
avergradrms
MONITOR_AVERAGE_GRADIENT
the root mean square value of the averaged
coefficient gradient. For multiple biases this
component is labeled using the number of the
bias as gradrms-#.
avergradmax
MONITOR_AVERAGE_GRADIENT
the largest absolute value of the averaged
coefficient gradient. For multiple biases this
component is labeled using the number of the
bias as gradmax-#.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
583
Compulsory keywords
BIAS
the label of the VES bias to be optimized
STRIDE
the frequency of updating the coefficients given in the number of MD steps.
COEFFS_FILE
( default=coeffs.data ) the name of output file for the coefficients
COEFFS_OUTPUT
( default=100 ) how often the coefficients should be written to file. This parameter is given
as the number of iterations.
Options
MONITOR_INSTANTANEOUS_GRADIENT
( default=off ) if quantities related to the instantaneous
gradient should be outputted.
MULTIPLE_WALKERS
( default=off ) if optimization is to be performed using
multiple walkers connected via MPI
MONITOR_AVERAGE_GRADIENT
( default=off ) if the averaged gradient should be monitored and quantities related to it should be outputted.
MONITOR_HESSIAN
( default=off ) also monitor the Hessian
COEFFS_FMT
specify format for coefficient file(s) (useful for decrease
the number of digits in regtests)
COEFFS_SET_ID_PREFIX
suffix to add to the filename given in FILE to identify
the bias, should only be given if a single filename is
given in FILE when optimizing multiple biases.
INITIAL_COEFFS
the name(s) of file(s) with the initial coefficients
TARGETDIST_AVERAGES_FILE
the name of output file for the target distribution averages. By default it is targetdist-averages.data.
TARGETDIST_AVERAGES_OUTPUT
how often the target distribution averages should be
written out to file. Note that the value is given in terms
of coefficient iterations. If no value is given are the averages only written at the beginning of the optimization
BIAS_OUTPUT
how often the bias(es) should be written out to file.
Note that the value is given in terms of coefficient iterations.
how often the FES(s) should be written out to file. Note
that the value is given in terms of coefficient iterations.
FES_OUTPUT
FES_PROJ_OUTPUT
RESTART
how often the projections of the FES(s) should be written out to file. Note that the value is given in terms of
coefficient iterations.
allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM
Only update this action from this time
UPDATE_UNTIL
Only update this action until this time
MONITOR_AVERAGES_GRADIENT_EXP_DECAY
use an exponentially decaying averaging with a given
time constant when monitoring the averaged gradient
Examples
In the following input we use the OPT_DUMMY to monitor the gradient and Hessian for a given VES bias every 1
iteration.
Generated by Doxygen
584
Additional Modules
BEGIN_PLUMED_FILE
phi:
TORSION ATOMS=5,7,9,15
bf1: BF_FOURIER ORDER=5 MINIMUM=-pi MAXIMUM=pi
VES_LINEAR_EXPANSION ...
ARG=phi
BASIS_FUNCTIONS=bf1
LABEL=ves1
TEMP=300.0
GRID_BINS=100
... VES_LINEAR_EXPANSION
OPT_DUMMY ...
BIAS=ves1
STRIDE=1000
LABEL=o1
MONITOR_HESSIAN
GRADIENT_FILE=gradient.data
GRADIENT_OUTPUT=1
GRADIENT_FMT=%12.6f
HESSIAN_FILE=hessian.data
HESSIAN_OUTPUT=1
HESSIAN_FMT=%12.6f
... OPT_DUMMY
8.6.4.3
OPT_ROBBINS_MONRO_SGD
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Robbins-Monro stochastic gradient decent.
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Quantity
Description
stepsize
the current value of step size used to update the coefficients. For multiple biases this component is
labeled using the number of the bias as stepsize-#.
In addition the following quantities can be calculated by employing the keywords listed below
Quantity
Keyword
Description
gradrms
MONITOR_INSTANTANEOUS_GRADIENT
the root mean square value of the coefficient
gradient. For multiple biases this component
is labeled using the number of the bias as
gradrms-#.
gradmax
MONITOR_INSTANTANEOUS_GRADIENT
the largest absolute value of the coefficient gradient. For multiple biases this component is labeled using the number of the bias as gradmax#.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
585
Compulsory keywords
BIAS
the label of the VES bias to be optimized
STRIDE
the frequency of updating the coefficients given in the number of MD steps.
COEFFS_FILE
( default=coeffs.data ) the name of output file for the coefficients
COEFFS_OUTPUT
( default=100 ) how often the coefficients should be written to file. This parameter is given
as the number of iterations.
the initial step size used for the optimization
INITIAL_STEPSIZE
Options
MONITOR_INSTANTANEOUS_GRADIENT
( default=off ) if quantities related to the instantaneous gradient
should be outputted.
MULTIPLE_WALKERS
( default=off ) if optimization is to be performed using multiple
walkers connected via MPI
( default=off ) if the iterations should be started afresh when a
restart has been triggered by the RESTART keyword or the MD
code.
START_OPTIMIZATION_AFRESH
COEFFS_FMT
specify format for coefficient file(s) (useful for decrease the number of digits in regtests)
COEFFS_SET_ID_PREFIX
suffix to add to the filename given in FILE to identify the bias,
should only be given if a single filename is given in FILE when
optimizing multiple biases.
INITIAL_COEFFS
the name(s) of file(s) with the initial coefficients
TARGETDIST_AVERAGES_FILE
the name of output file for the target distribution averages. By
default it is targetdist-averages.data.
TARGETDIST_AVERAGES_OUTPUT
how often the target distribution averages should be written out
to file. Note that the value is given in terms of coefficient iterations. If no value is given are the averages only written at the
beginning of the optimization
BIAS_OUTPUT
how often the bias(es) should be written out to file. Note that the
value is given in terms of coefficient iterations.
FES_OUTPUT
how often the FES(s) should be written out to file. Note that the
value is given in terms of coefficient iterations.
FES_PROJ_OUTPUT
how often the projections of the FES(s) should be written out to
file. Note that the value is given in terms of coefficient iterations.
RESTART
allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM
Only update this action from this time
UPDATE_UNTIL
Only update this action until this time
MASK_FILE
read in a mask file which allows one to employ different step
sizes for different coefficients and/or deactivate the optimization
of certain coefficients (by putting values of 0.0). One can write
out the resulting mask by using the OUTPUT_MASK_FILE keyword.
Name of the file to write out the mask resulting from using the
MASK_FILE keyword. Can also be used to generate a template
mask file.
stride for updating a target distribution that is iteratively updated
during the optimization. Note that the value is given in terms of
coefficient iterations.
OUTPUT_MASK_FILE
TARGETDIST_STRIDE
Generated by Doxygen
586
Additional Modules
TARGETDIST_OUTPUT
TARGETDIST_PROJ_OUTPUT
DECAY_CONSTANT
how often the dynamic target distribution(s) should be written
out to file. Note that the value is given in terms of coefficient
iterations.
how often the projections of the dynamic target distribution(s)
should be written out to file. Note that the value is given in terms
of coefficient iterations.
the decay constant used for the step size.
Examples
8.6.4.4
OPT_STEEPEST_DECENT
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Steepest decent optimizer.
Description of components
The names of the components in this action can be customized by the user in the actions input file. However, in
addition to the components that can be customized the following quantities will always be output
Quantity
Keyword
Description
gradrms
MONITOR_INSTANTANEOUS_GRADIENT
the root mean square value of the coefficient
gradient. For multiple biases this component
is labeled using the number of the bias as
gradrms-#.
gradmax
MONITOR_INSTANTANEOUS_GRADIENT
the largest absolute value of the coefficient gradient. For multiple biases this component is labeled using the number of the bias as gradmax#.
Compulsory keywords
BIAS
the label of the VES bias to be optimized
STRIDE
the frequency of updating the coefficients given in the number of MD steps.
COEFFS_FILE
( default=coeffs.data ) the name of output file for the coefficients
COEFFS_OUTPUT
( default=100 ) how often the coefficients should be written to file. This parameter is given
as the number of iterations.
the step size used for the optimization
STEPSIZE
Options
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
587
MONITOR_INSTANTANEOUS_GRADIENT
( default=off ) if quantities related to the instantaneous gradient
should be outputted.
MULTIPLE_WALKERS
( default=off ) if optimization is to be performed using multiple
walkers connected via MPI
COEFFS_FMT
specify format for coefficient file(s) (useful for decrease the number of digits in regtests)
COEFFS_SET_ID_PREFIX
suffix to add to the filename given in FILE to identify the bias,
should only be given if a single filename is given in FILE when
optimizing multiple biases.
INITIAL_COEFFS
the name(s) of file(s) with the initial coefficients
TARGETDIST_AVERAGES_FILE
the name of output file for the target distribution averages. By
default it is targetdist-averages.data.
TARGETDIST_AVERAGES_OUTPUT
how often the target distribution averages should be written out
to file. Note that the value is given in terms of coefficient iterations. If no value is given are the averages only written at the
beginning of the optimization
BIAS_OUTPUT
how often the bias(es) should be written out to file. Note that the
value is given in terms of coefficient iterations.
FES_OUTPUT
how often the FES(s) should be written out to file. Note that the
value is given in terms of coefficient iterations.
FES_PROJ_OUTPUT
how often the projections of the FES(s) should be written out to
file. Note that the value is given in terms of coefficient iterations.
RESTART
allows per-action setting of restart (YES/NO/AUTO)
UPDATE_FROM
Only update this action from this time
UPDATE_UNTIL
Only update this action until this time
MASK_FILE
read in a mask file which allows one to employ different step
sizes for different coefficients and/or deactivate the optimization
of certain coefficients (by putting values of 0.0). One can write
out the resulting mask by using the OUTPUT_MASK_FILE keyword.
Name of the file to write out the mask resulting from using the
MASK_FILE keyword. Can also be used to generate a template
mask file.
OUTPUT_MASK_FILE
Examples
8.6.5
Utilities
The following list contains various utilities available in the VES code.
VES_OUTPUT_BASISFUNCTIONS
Output basis functions to file.
VES_OUTPUT_FES
Tool to output biases and free energy surfaces for VES biases
from previously obtained coefficients.
VES_OUTPUT_TARGET_DISTRIBUTION
Output target distribution to file.
8.6.5.1
VES_OUTPUT_BASISFUNCTIONS
Generated by Doxygen
588
Additional Modules
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Output basis functions to file.
This action can be used to write out to a grid file the values and derivatives of given basis functions. This is normally
used for debugging when programming new types of basis functions. For example, it is possible to calculate the
derivatives numerically and compare to the analytically calculated derivatives.
This action is normally used through the driver.
Compulsory keywords
BASIS_FUNCTIONS
the label of the basis functions that you want to use
Options
IGNORE_PERIODICITY
NUMERICAL_DERIVATIVES
GRID_BINS
GRID_MIN
GRID_MAX
FILE_VALUES
FILE_DERIVS
( default=off ) if the periodicity of the basis functions should be ignored.
( default=off ) if the derivatives of the basis functions should be calculated numerically.
the number of bins used for the grid for writing the basis function
values and derivatives. The default value is 1000.
the minimum of the grid for writing the basis function values and
derivatives. By default it is the minimum of the interval on which the
basis functions are defined.
the maximum of the grid for writing the basis function values and
derivatives. By default it is the maximum of the interval on which
the basis functions are defined.
filename of the file on which the basis function values are written. By
default it is BF_LABEL.values.data.
filename of the file on which the basis function derivatives are written.
By default it is BF_LABEL.derivs.data.
FORMAT_VALUES_DERIVS
the numerical format of the basis function values and derivatives written to file. By default it is %15.8f.
FILE_TARGETDIST_AVERAGES
filename of the file on which the averages over the target distributions
are written. By default it is BF_LABEL.targetdist-averages.data.
FORMAT_TARGETDIST_AVERAGES
the numerical format of the target distribution averages written to file.
By default it is %15.8f.
FILE_INNER_PRODUCTS
filename of the file on which the inner products of the basis functions
are written. By default it is BF_LABEL.inner-products.data.
FORMAT_INNER_PRODUCTS
the numerical format of the inner products of the basis functions written to file. By default it is %15.8f.
FILE_TARGETDIST
filename of the files on which the target distributions are written. By
default it is BF_LABEL.targetdist-#.data.
TARGET_DISTRIBUTION
the target distribution to be used. You can use multiple instances of
this keyword i.e. TARGET_DISTRIBUTION1, TARGET_DISTRIBU←TION2, TARGET_DISTRIBUTION3...
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
589
Examples
In the following input we define a Legendre polynomials basis functions of order 14 over the interval -4.0 to 4.0 and
output their values and derivatives to files called bfL.values.data and bfL.derivs.data.
BEGIN_PLUMED_FILE
BF_LEGENDRE ...
ORDER=14
MINIMUM=-4.0
MAXIMUM=4.0
LABEL=bfL
... BF_LEGENDRE
VES_OUTPUT_BASISFUNCTIONS ...
BASIS_FUNCTIONS=bfL
GRID_BINS=200
FORMAT_VALUES_DERIVS=%13.6f
... VES_OUTPUT_BASISFUNCTIONS
This input should be run through the driver by using a command similar to the following one where the trajectory/configuration file configuration.gro is needed to trick the code to exit correctly.
plumed driver --plumed plumed.dat --igro configuration.gro
8.6.5.2
VES_OUTPUT_FES
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Tool to output biases and free energy surfaces for VES biases from previously obtained coefficients.
This action can be used to output to file biases and free energy surfaces for VES biases from previously obtained
coefficients. It should be used through the driver and can only be used in post processing. The VES bias needs
to be defined in the exact same way as during the simulation. At the current moment this action does not support
dynamic target distributions (e.g. well-tempered).
Compulsory keywords
BIAS
the label of the VES bias for to output the free energy surfaces and the bias files
COEFFS_INPUT
the name of input coefficient file
Options
BIAS_OUTPUT
FES_OUTPUT
Generated by Doxygen
how often the bias(es) should be written out to file. Note that the value is given in terms
of coefficient iterations.
how often the FES(s) should be written out to file. Note that the value is given in terms
of coefficient iterations.
590
Additional Modules
FES_PROJ_OUTPUT
how often the projections of the FES(s) should be written out to file. Note that the value
is given in terms of coefficient iterations.
Examples
In the following input we define a VES bias and then read in the coefficient file coeffs.input.data and output the FES
and bias every 500 iterations.
BEGIN_PLUMED_FILE
phi:
TORSION ATOMS=5,7,9,15
psi:
TORSION ATOMS=7,9,15,17
bf1: BF_FOURIER ORDER=5 MINIMUM=-pi MAXIMUM=pi
bf2: BF_FOURIER ORDER=5 MINIMUM=-pi MAXIMUM=pi
VES_LINEAR_EXPANSION ...
ARG=phi,psi
BASIS_FUNCTIONS=bf1,bf2
LABEL=ves1
GRID_BINS=100,100
PROJ_ARG1=phi
PROJ_ARG2=psi
... VES_LINEAR_EXPANSION
VES_OUTPUT_FES ...
BIAS=ves1
FES_OUTPUT=500
FES_PROJ_OUTPUT=500
BIAS_OUTPUT=500
COEFFS_INPUT=coeffs.input.data
... VES_OUTPUT_FES
This input should be run through the driver by using a command similar to the following one where the trajectory/configuration file configuration.gro is needed to correctly define the CVs
plumed driver --plumed plumed.dat --igro configuration.gro
8.6.5.3
VES_OUTPUT_TARGET_DISTRIBUTION
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Output target distribution to file.
This action can be used to output target distributions to a grid file, for example to see how they look like before using
them in a VES bias. This action only support static target distributions.
This action is normally used through the driver.
Compulsory keywords
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
GRID_MIN
the lower bounds for the grid
GRID_MAX
the upper bounds for the grid
GRID_BINS
the number of bins used for the grid.
TARGETDIST_FILE
filename of the file for writing the target distribution
TARGET_DISTRIBUTION
the target distribution to be used.
591
Options
DO_1D_PROJECTIONS
( default=off ) Also output the one-dimensional marginal distributions for multidimensional target distribution.
GRID_PERIODICITY
specify if the individual arguments should be made periodic (YES) or not (NO). By
default all arguments are taken as not periodic.
LOG_TARGETDIST_FILE
filename of the file for writing the log of the target distribution
FMT_GRIDS
the numerical format of the target distribution grids written to file. By default it is
%14.9f
Examples
In the following input we define a target distribution that is uniform for argument 1 and a Gaussian for argument 2
and then output it to a file called targetdist-1.data.
BEGIN_PLUMED_FILE
t1_1: TD_UNIFORM MINIMA=-4.0 MAXIMA=+4.0
t1_2: TD_GAUSSIAN CENTER1=-2.0 SIGMA1=0.5
t1: TD_PRODUCT_DISTRIBUTION DISTRIBUTIONS=t1_1,t1_2
VES_OUTPUT_TARGET_DISTRIBUTION ...
GRID_MIN=-4.0,-4.0
GRID_MAX=+4.0,+4.0
GRID_BINS=100,100
TARGET_DISTRIBUTION=t1
TARGETDIST_FILE=targetdist-1.data
LOG_TARGETDIST_FILE=targetdist-1.log.data
FMT_GRIDS=%11.6f
... VES_OUTPUT_TARGET_DISTRIBUTION
This input should be run through the driver by using a command similar to the following one where the trajectory/configuration file configuration.gro is needed to trick the code to exit correctly.
plumed driver --plumed plumed.dat --igro configuration.gro
8.6.6
Command Line Tools
The following list contains the command line tools available in the VES code.
ves_md_linearexpansion
Generated by Doxygen
Simple MD code for dynamics on a potential energy surface given by a linear basis
set expansion.
592
Additional Modules
8.6.6.1
ves_md_linearexpansion
This is part of the ves module
It is only available if you configure PLUMED with ./configure –enable-modules=ves . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Simple MD code for dynamics on a potential energy surface given by a linear basis set expansion.
This is simple MD code that allows running dynamics of a single particle on a potential energy surface given by
some linear basis set expansion in one to three dimensions.
It is possible to run more than one replica of the system in parallel.
Compulsory keywords
nstep
( default=10 ) The number of steps of dynamics you want to run.
tstep
( default=0.005 ) The integration timestep.
temperature
( default=1.0 ) The temperature to perform the simulation at. For multiple replica you
can give a separate value for each replica.
friction
( default=10. ) The friction of the Langevin thermostat. For multiple replica you can
give a separate value for each replica.
random_seed
( default=5293818 ) Value of random number seed.
plumed_input
( default=plumed.dat ) The name of the plumed input file(s). For multiple replica you
can give a separate value for each replica.
dimension
( default=1 ) Number of dimensions, supports 1 to 3.
initial_position
Initial position of the particle. For multiple replica you can give a separate value for
each replica.
replicas
( default=1 ) Number of replicas.
basis_functions_1
input_coeffs
Basis functions for dimension 1.
( default=potential-coeffs.in.data ) Filename of the input coefficient file for the potential.
For multiple replica you can give a separate value for each replica.
output_coeffs
( default=potential-coeffs.out.data ) Filename of the output coefficient file for the potential.
( default=%30.16e ) Format of the output coefficient file for the potential. Useful for
regtests.
output_coeffs_fmt
output_potential_grid
output_potential
( default=100 ) The number of grid points used for the potential and histogram output
files.
( default=potential.data ) Filename of the potential output file.
output_histogram
( default=histogram.data ) Filename of the histogram output file.
Options
--help/-h
( default=off ) print this help
basis_functions_2
basis_functions_3
coeffs_prefactor
Basis functions for dimension 2 if needed.
Basis functions for dimension 3 if needed.
prefactor for multiplying the coefficients with. For multiple replica you can give a separate value for each replica.
template_coeffs_file
only generate a template coefficient file with the filename given and exit.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
593
Examples
In the following example we perform dynamics on the Wolfe-Quapp potential that is defined as
U (x, y) = x4 + y 4 − 2x2 − 4y 2 + xy + 0.3x + 0.1y
To define the potential we employ polynomial power basis functions (BF_POWERS). The input file is given as
nstep
10000
tstep
0.005
temperature
1.0
friction
10.0
random_seed
4525
plumed_input
plumed.dat
dimension
2
replicas
1
basis_functions_1 BF_POWERS ORDER=4 MINIMUM=-3.0 MAXIMUM=+3.0
basis_functions_2 BF_POWERS ORDER=4 MINIMUM=-3.0 MAXIMUM=+3.0
input_coeffs
pot_coeffs_input.data
initial_position
-1.174,+1.477
output_potential
potential.data
output_potential_grid
150
output_histogram
histogram.data
#
#
#
#
#
Wolfe-Quapp potential given by the equation
U(x,y) = x**4 + y**4 - 2.0*x**2 - 4.0*y**2 + x*y + 0.3*x + 0.1*y
Minima around (-1.174,1.477); (-0.831,-1.366); (1.124,-1.486)
Maxima around (0.100,0.050)
Saddle points around (-1.013,-0.036); (0.093,0.174); (-0.208,-1.407)
This input is then run by using the following command.
plumed ves_md_linearexpansion input
The corresponding pot_coeffs_input.data file is
#!
#!
#!
#!
#!
#!
FIELDS idx_dim1 idx_dim2 pot.coeffs index description
SET type LinearBasisSet
SET ndimensions 2
SET ncoeffs_total 25
SET shape_dim1 5
SET shape_dim2 5
0
0
0.0000000000000000e+00
0
1
0
0.3000000000000000e+00
1
2
0
-2.0000000000000000e+00
2
4
0
1.0000000000000000e+00
4
0
1
0.1000000000000000e+00
5
1
1
+1.0000000000000000e+00
6
0
2
-4.0000000000000000e+00
10
0
4
1.0000000000000000e+00
20
#!-------------------
1*1
s^1*1
s^2*1
s^4*1
1*s^1
s^1*s^1
1*s^2
1*s^4
One then uses the (x,y) position of the particle as CVs by using the POSITION action as shown in the following
PLUMED input
BEGIN_PLUMED_FILE
p: POSITION ATOM=1
ene: ENERGY
PRINT ARG=p.x,p.y,ene FILE=colvar.data FMT=%8.4f
8.6.7
Tutorials
The following tutorials are available for the VES code.
MARVEL-VES School February 2017
Generated by Doxygen
594
Additional Modules
MARVEL-VES tutorial (Lugano Feb 2017): MetadynamicsBrief introduction to metadynamics.
MARVEL-VES tutorial (Lugano Feb 2017): VES 1
MARVEL-VES tutorial (Lugano Feb 2017): VES 2
MARVEL-VES tutorial (Lugano Feb 2017): Kinetics
8.6.7.1
Introduction to VES, using different target distributions
and basis sets.
VES, well-tempered target distribution and 2 dimensional biases.
How to obtain kinetics from biased molecular simulations using VES.
MARVEL-VES School February 2017
Tutorials from the MARVEL School on Variationally Enhanced Sampling that was held in Lugano,
February 14-17, 2017.
Suggested readings
Metadynamics:
Enhancing Important Fluctuations: Rare Events and Metadynamics from a Conceptual
Viewpoint, Annual Reviews in Physical Chemistry 2016
Variationally Enhanced Sampling:
Variational Approach to Enhanced Sampling and Free Energy Calculations, Physical Review Letters 2014
Variationally Optimized Free-Energy Flooding for Rate Calculation, Physical Review Letters 2015
Tuesday February 14
Tutorial 1: Introduction to PLUMED and analyzing molecular simulations
Wednesday February 15
Tutorial 2: Biasing with metadynamics
Tutorial 3: Biasing with variationally enhanced sampling
Thursday February 16
Tutorial 4: Further on variationally enhanced sampling
Tutorial 5: Advanced collective variables
• Path CVs
• Multicolvar
• Dimensionality reduction
Friday February 17
Tutorial 6: Obtaining kinetics from molecular simulations
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
8.6.7.2
595
MARVEL-VES tutorial (Lugano Feb 2017): Metadynamics
8.6.7.2.1
Learning Outcomes
Once this tutorial is completed students will learn to:
• Perform metadynamics simulations using PLUMED 2 and LAMMPS
• Construct a bias potential on 1 and 2 collective variables (CVs)
• Assess the convergence of the free energy surface
• Distinguish between good and bad CVs
• Reweight with more than one bias potential
8.6.7.2.2
Resources
The tarball for this project contains the following folders:
• Example1 : Contains the input file for the unbiased simulation.
• Example2 : Contains the input files for one of the biased simulations. The rest of the biased simulations
inputs should be created by modifying this one.
8.6.7.2.3
8.6.7.2.3.1
Instructions
The system
We consider the association/dissociation of NaCl in aqueous solution. The dissociation barrier is expected to be
around 2.5 kB T . One interesting aspect of the ion dissociation problem is that collective solvent motions play an
important role in the transition. This problem has been considered in the original metadynamics paper [45] and
also in reference [89] . We will use the potential developed in ref. [90] for NaCl and TIP3P water with parameters
corrected to be used with long-range Coulomb solvers [91]. The system contains 1 Na, 1 Cl, and 106 water
molecules (total 320 atoms).
8.6.7.2.3.2
Perform an unbiased simulation and control the distance Na-Cl
We first perform a standard MD simulation and control the distance Na-Cl. All the files needed for this example are
contained in the folder Example1 . The distance Na-Cl can be calculated in Plumed 2 using:
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=319,320
The coordination number of Na with respect to O in water will also be calculated for later use. This variable will
represent the collective motion of the solvent.
BEGIN_PLUMED_FILE
COORDINATION ...
GROUPA=319
GROUPB=1-318:3
SWITCH={RATIONAL R_0=0.315 D_MAX=0.5 NN=12 MM=24}
NLIST
NL_CUTOFF=0.55
NL_STRIDE=10
LABEL=coord
... COORDINATION
Generated by Doxygen
596
Additional Modules
To run LAMMPS you can use the run.sh script:
#!/bin/bash
############################################################################
# Definition of variables
############################################################################
EXE=lmp_mpi
totalCores=2
############################################################################
mpirun -np ${totalCores} ${EXE} < start.lmp > out.lmp
This command runs LAMMPS using 2 MPI threads. The use of partitions will be discussed when using multiple
walkers
Once the simulation is launched, the so called COLVAR file is written. In this case it contains the following:
#! FIELDS
0.200000
0.400000
0.600000
0.800000
1.000000
1.200000
1.400000
1.600000
1.800000
2.000000
.
.
.
time d1 coord
0.568067 5.506808
0.500148 4.994588
0.449778 4.931140
0.528272 5.105816
0.474371 5.089863
0.430620 5.091551
0.470374 4.993886
0.458768 4.940097
0.471886 4.952868
0.489058 4.897593
If you plot the time (column 1) vs the distance (column 2), for instance in gnuplot:
pl
"./COLVAR" u 1:2 w lp,
you will see that the ion pair is stuck in the dissociated state during the 1 ns simulation. It is unable to cross the
∼ 5kB T barrier located at a distance of approximately 0.4 nm. You can also observe this behavior in the trajectory
using VMD:
vmd out.dcd -psf nacl.psf
The trajectory has been saved in unwrapped format in order to avoid bonds stretching from one side to the box
to the other due to periodic boundary conditions. In VMD we can wrap the atoms without breaking the bonds and
show the box using the commands:
pbc wrap -compound res -all
pbc box
You can play with different visualization styles and options that VMD has. Therefore, if we want the system to go
back and forth between the associated and dissociated state, we will need enhanced sampling.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
8.6.7.2.3.3
597
Construct a bias potential on the distance Na-Cl
We now construct a bias potential V (s) on the distance Na-Cl using well-tempered metadynamics. The files for
this example are contained in the directory Example2. As argument for the construction of the potential we will use
the distance Na-Cl (label d1). We choose a gaussian height of 1 kJ/mol which is slightly less than 0.5 kB T . The
gaussian width is 0.02 nm, in the same order of the features in the FES. A rule of thumb for choosing the gaussian
width is to use the standard deviation of the unbiased fluctuations of the CV. The bias factor is set to 5 since the
largest barrier in the FES is expected to be roughly 5 kB T . Once the metadynamics simulation is converged, the
bias will be (up to an arbitrary constant):
1
F (s)
V (s) = − 1 −
γ
and therefore the system will evolve under an effective free energy:
F̃ (s) = F (s) + V (s) =
F (s)
,
γ
that is to say, the largest barrier will be of around 1 kB T . The input is:
BEGIN_PLUMED_FILE
METAD ...
LABEL=metad
ARG=d1
SIGMA=0.02
HEIGHT=1.
BIASFACTOR=5
TEMP=300.0
PACE=500
GRID_MIN=0.2
GRID_MAX=1.0
GRID_BIN=300
REWEIGHTING_NGRID=300
... METAD
Here the REWEIGHTING_NGRID keyword turns on the calculation of the time dependent constant c(t) that we will
use below when reweighting the simulations.
We will also limit the exploration of the CV space by introducing an upper wall bias Vwall (s):
Vwall (s) = κ(s − s0 )2 if s > s0 and 0 otherwise.
The wall will focus the sampling in the most interesting region of the free energy surface. The effect of this bias
potential will have to be corrected later in order to calculate ensemble averages. The syntax in Plumed 2 is:
BEGIN_PLUMED_FILE
UPPER_WALLS ...
ARG=d1
AT=0.6
KAPPA=2000.0
EXP=2
EPS=1
OFFSET=0.
LABEL=uwall
... UPPER_WALLS
You can run the simulation with the run.sh script as done in the previous example.
It is possible to try different bias factors to check the effect that it has on the trajectory and the effective FES.
In principle the cost of a metadynamics simulation should increase as the simulation progresses due to the need of
adding an increasing number of Gaussian kernels to calculate the bias. However, since a grid is used to build up the
bias this effect is not observed. You can check what happens if you do not use the GRID_∗ keywords. Remember
that the bins in the grid should be small enough to describe the changes in the bias created by the Gaussian kernels.
Normally a bin of size σ/5 (with σ the gaussian width) is small enough.
Generated by Doxygen
598
8.6.7.2.3.4
Additional Modules
Assess convergence
One way to identify if a well tempered metadynamics simulation has converged is observing the estimated free
energy surface at different times. The FES is estimated by using the relation (again up to an arbitrary constant):
F (s) = −
γ
γ−1
V (s, t)
and the bias potential is calculated as a sum of Gaussian kernels. This can be done with Plumed 2 using for
instance:
plumed sum_hills --hills ../HILLS --min 0.1 --max 0.8 --bin 300 --stride 100
Most of the flags are self explanatory. The flag –stride 100 will result in the FES been written every 100 Gaussian
kernels, i.e. 100 ps. Inside the folder FES_calculation you will find a script run.sh that executes the sum_hills
command and a gnuplot script plot.gpi that can be used typing:.
gnuplot plot.gpi
After roughly 3 ns the free energy surface does not change significantly with time except for an immaterial constant
c(t) that grows in time. This is in line with well-tempered metadynamics asymptotic behavior:
1
F (s) + c(t).
V (s, t) = − 1 −
γ
The behavior of c(t) will be studied with greater detail later. It should be stressed that we are actually not calculating
the free energy F (s) but rather F (s) + Vwall (s). For this reason for distances higher than 0.6 nm the free energy
increases sharply.
An alternative way to observe the evolution of the bias is plotting the final free energy plus the instantaneous bias.
The scripts for this example can be found in the folder Bias_calculation. In this case we observe only the first 200
ps of the simulation. The (negative) bias can be calculated using:
plumed sum_hills --hills ../HILLS --min 0.1 --max 0.8 --bin 300 --stride 10 --negbias
This plot illustrates clearly how the bias is constructed to progressively "fill" the FES.
It is also possible to track convergence by controlling the evolution of some quantity connected to the free energy
surface. In this case we will calculate the dissociation barrier, e.g. the height of the barrier that separates the
associated state from the dissociated one. The scripts for this example are found in the folder Barrier_calculation.
Using the python script calculate_barrier.py we can compute the barrier, for instance:
import numpy as np
# Total number of fes files in folder
total_files=101
# Min and max initial guesses
min_min=50
min_max=90
max_min=90
max_max=130
for i in range(total_files):
file_name="fes_" + str(i) + ".dat"
matrix=np.genfromtxt(file_name)
minimum=np.amin(matrix[min_min:min_max,1])
maximum=np.amax(matrix[max_min:max_max,1])
print(str(i) + " " + str(minimum) + " " + str(maximum) + " " + str(maximum-minimum))
The script can be executed using:
python barrier_calculation.py > barrier.txt
and the results can be plotted using the gnuplot script plot.gpi. After roughly 4 ns the barrier stabilizes around 3 and
3.5 kB T . It is important to stress that it is only possible to calculate the free energy difference between two points
if the system has gone back and forth between these points several times. This applies both for the calculation of
a barrier and the difference in free energy between two basins. It is also important to understand that none of the
free energy methods described in this series of tutorials will be able to calculate free energies of regions that have
not been sampled, i.e. visited.
Reweighting the simulation on the same CV that was used for biasing can also be used as a test of convergence.
We will show that in the next section.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
8.6.7.2.3.5
599
Reweight the simulation
We first reweight the simulation on the distance Na-Cl, the same CV used for biasing. This reweighting is useful to
check convergence and to have an estimate of the free energy that does not rely on using kernels. For instance if
some features of the FES could not be captured by the kernels, the reweighting procedure will show them. This will
become clearer in the VES tutorial. The scripts to perform this calculation are found in the folder ReweightDistance.
In metadynamics quasi-stationary limit the weight assigned to a given configuration is [3] :
w(R) ∝ eβ(V (s,t)−c(t)) .
By plotting time (column 1) versus c(t) (column 6) using the COLVAR file, the importance of taking c(t) into account
becomes clear. c(t) keeps growing even after long times, reflecting the approximately rigid shift of the bias with
time. Normally the first part of the trajectory is not used for reweighting since during this period the simulation has
not reached the quasi-stationary limit. In this case we can discard the first 2 or 3 ns of simulation. To disregard the
first 3 ns of simulation we can use sed to delete the first 15000 lines from the COLVAR file:
sed ’2,15000d’ ../COLVAR > COLVAR
We then use Plumed to calculate two histograms, one taking into account the wall bias and the other one neglecting
it. The weights for the reweighting involving only the metadynamics bias have already been discussed while the
weights considering both biases are:
w(R) ∝ eβ(V (s,t)−c(t)+Vwall (s)) .
The input script for Plumed is:
BEGIN_PLUMED_FILE
# Read COLVAR file
distance:
READ FILE=COLVAR IGNORE_TIME VALUES=d1
metad:
READ FILE=COLVAR IGNORE_TIME VALUES=metad.rbias
uwall:
READ FILE=COLVAR IGNORE_TIME VALUES=uwall.bias
# Define weights
weights1: REWEIGHT_METAD TEMP=300
weights2: REWEIGHT_BIAS TEMP=300 ARG=metad.rbias,uwall.bias
# Calculate histograms
HISTOGRAM ...
ARG=distance
GRID_MIN=0.2
GRID_MAX=0.8
GRID_BIN=100
BANDWIDTH=0.002
LOGWEIGHTS=weights1
LABEL=hh1
... HISTOGRAM
HISTOGRAM ...
ARG=distance
GRID_MIN=0.2
GRID_MAX=0.8
GRID_BIN=100
BANDWIDTH=0.002
LOGWEIGHTS=weights2
LABEL=hh2
... HISTOGRAM
# Print histograms to file
DUMPGRID GRID=hh1 FILE=histo FMT=%24.16e
DUMPGRID GRID=hh2 FILE=histo_wall FMT=%24.16e
This example can be run with:
plumed --no-mpi driver --plumed plumed.dat --noatoms > plumed.out
Generated by Doxygen
600
Additional Modules
and will generate the files histo and histo_wall. The histograms represent the probability p(s) of observing a given
value of the CV s . From the histograms the FES can be calculated using:
βF (s) = − log p(s)
and therefore we plot the FES in gnuplot using for instance:
pl
"./histo" u 1:(-log($2)) w lp
The next plot compares the estimations of the FES from sum_hills, reweighting with metadynamics bias, and
reweighting using both the metadynamics bias and the upper wall bias You will find a gnuplot script plot.gpi to
make this plot inside the ReweightDistance folder.
We can obtain important information of the system by reweighting on 2 CVs: The distance Na-Cl and the coordination of Na with O. This reweighting is similar to the one already done and the files that you will need are located
in the ReweightBoth folder. Additionally the COLVAR file with the omitted first steps is required. The plot of the
FES as a function of these 2 CVs provides important information of the association/dissociation mechanism. In the
dissociated state, Na can have a coordination of 5 or 6, though it is more likely to find a coordination number of
6. However, in order to associate Na must have a coordination with O of 5. In the associated state Na can have a
coordination of 3, 4 or 5. The transition state is characterized by a coordination number of ∼5.
8.6.7.2.3.6
Construct a bias potential on the coordination Na-O
As an exercise, you can write the input files for a simulation in which a bias potential is constructed on the coordination Na-0, i.e. the solvent degree of freedom. You can use the same gaussian height as before and σ = 0.1.
You will find that the exploration of the CV space is not efficient. The reason is that there is a slow degree of
freedom that it is not being biased: the distance Na-Cl. Furthermore you can see in the 2 CV reweighting that the
coordination Na-O shows significant overlap between the associated and dissociated states.
Bear in mind that this is a rather trivial example since the existing barriers are relatively low. Real problems in
materials science usually involve large barriers and are not as forgiving as this example; a bad CV may lead to huge
hysteresis and problems in convergence.
8.6.7.2.3.7
Construct a bias potential on both CVs
We will now construct a bias potential on both CVs. We have already calculated the FES as a function of both
CVs through reweighting. In this example the FES will be calculated using the metadynamics bias potential. You
can use the input files from Example2.tar and changed the plumed.dat file. To construct a 2 dimensional bias with
metadynamics use the following input:
BEGIN_PLUMED_FILE
METAD ...
LABEL=metad
ARG=d1,coord
SIGMA=0.02,0.1
HEIGHT=1.
BIASFACTOR=5
TEMP=300.0
PACE=500
GRID_MIN=0.15,2.
GRID_MAX=0.9,9.
GRID_BIN=400,400
REWEIGHTING_NGRID=400,400
... METAD
Once that the simulation is completed you can run plumed sum_hills to calculate the FES:
plumed sum_hills --hills HILLS --mintozero
and plot the results using the following lines in gnuplot:
set pm3d map
set zr [0:15]
spl "fes.dat" u 1:2:3
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
8.6.7.2.4
601
Final remarks
Some valuable tools for metadynamics simulations will be discussed in the VES tutorial. These include:
• Restarting a simulation.
• Using Plumed driver to calculate a CV that was not calculated during the simulation. A reweighting can then
be performed on this CV.
• Constructing biased histograms, i.e. histograms without weights to calculate the effective FES F̃ (s) = F (s)+
V (s).
• Use multiple walkers to improve the exploration of CV space.
8.6.7.3
8.6.7.3.1
MARVEL-VES tutorial (Lugano Feb 2017): VES 1
Learning Outcomes
Once this tutorial is completed students will learn to:
• Use different target distributions and choose the most appropriate for their problem.
• Use different basis sets and order of the expansions. Select the appropriate order for their problem.
• Use the optimization algorithm and choose the parameters.
• Construct biases in 1 dimension.
• Assess the convergence of the simulation.
• Obtain biased and unbiased histograms.
8.6.7.3.2
Resources
The tarball for this project contains the following folders:
• Example1 : Contains the input file for the first example.
• Example2 : Contains the input file for the second example.
Generated by Doxygen
602
Additional Modules
8.6.7.3.3
Summary of theory
Variationally enhanced sampling [69] is based on the the following functional of the bias potential:
1
Ω[V ] = log
β
R
ds e−β[F (s)+V (s)]
R
+
ds e−βF (s)
Z
ds p(s)V (s),
where s are the CVs to be biased, p(s) is a predefined probability distribution that we will refer to as the target
distribution, and F (s) is the free energy surface. This functional can be shown to be convex and to have a minimum
at:
V (s) = −F (s) −
1
log p(s).
β
The last equation states that once that the functional Ω[V ] is minimized, the bias and the target distribution allow
calculating the free energy. The target distribution p(s) can be chosen at will and it is the distribution of the CVs
once that Ω[V ] has been minimized.
The variational principle is put to practice by expanding V (s) in some basis set:
V (s) =
X
αi fi (s),
i
where fi (s) are the basis functions and the α are the coefficients in the expansion. We then need to find the α that
minimize Ω[V ]. In principle one could use any optimization algorithm. In practice the algorithm that has become
the default choice for VES is the so-called averaged stochastic gradient descent algorithm [88]. In this algorithm the
α are evolved iteratively according to:
h
i
α(n+1) = α(n) − µ ∇Ω(ᾱ(n) ) + H(ᾱ(n) )[α(n) − ᾱ(n) ]
where µ is the step size, ᾱ(n) is the running average of α(n) at iteration n, and ∇Ω(ᾱ(n) ) and H(ᾱ(n) ) are the
gradient and Hessian of Ω[V ] evaluated at the running average at iteration n, respectively. The behavior of the
coefficients will become clear in the examples below.
8.6.7.3.4
8.6.7.3.4.1
Instructions
The system
We will consider the same system employed for the metadynamics tutorial.
8.6.7.3.4.2
Example 1: First VES simulation
For the first VES simulation we will revisit the problem of the ion pair dissociation but replacing the metadynamics
bias with a VES bias. The bias potential will be constructed on the distance Na-Cl as done before. We will still use
the upper wall used in the metadynamics tutorial to make the actual example as similar as possible to the previous
one. We will then see that VES has a more natural way to deal with barriers. All files needed for this example can
be found in the Example1 folder.
Every VES simulation has three key ingredients:
• Basis set
• Target distribution
• Optimization algorithm
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
603
For the basis set we will choose Legendre polynomials defined in the interval [0.23,0.7] nm. Legendre polynomials
are a good choice for non-periodic CVs. A rule of thumb for choosing the order of the expansion is that an expansion
of order N can capture features of the FES of approximately L/N where L is the length of the interval. In this case,
an order of 10 is able to capture features of the order of around 0.05 nm. We will see afterwards that the order of
the expansion is not critical as long as we obtain good sampling at convergence. If this is the case, it is possible to
obtain finer features of the FES through reweighting. The syntax for this basis set in Plumed is:
BEGIN_PLUMED_FILE
BF_LEGENDRE ...
ORDER=10
MINIMUM=0.23
MAXIMUM=0.8
LABEL=bf1
... BF_LEGENDRE
We will use a uniform target distribution:
p(s) = 1/C
with C a normalization constant. Once that Ω[V ] is minimized, the bias potential satisfies (up to an arbitrary
constant):
V (s) = −F (s)
This is the same relation that holds for non-tempered metadynamics.
The syntax for the bias potential in Plumed is:
BEGIN_PLUMED_FILE
td1: TD_UNIFORM
VES_LINEAR_EXPANSION ...
ARG=d1
BASIS_FUNCTIONS=bf1
GRID_BINS=300
TARGET_DISTRIBUTION=td1
LABEL=b1
... VES_LINEAR_EXPANSION
Finally we have to choose the optimization algorithm. The standard is the averaged stochastic gradient descent.
One has to define two parameters: the stride and the step size. The stride is the number of steps in which samples
are collected to calculate the gradient and hessian of Ω[V ] and the step size is the step by which the coefficients
are evolved at every optimization steps. Both of this parameters are connected. Increasing the stride will have an
effect similar to reducing the step size. It has become traditional to choose a stride of around 500-2000 steps. It
must be noted that we are not looking for an accurate estimation of the gradient, since for this we would need to
sample all the CV space. The step size in the optimization has a strong connection with the height of typical barriers
in the system. The larger the barriers, the larger the step size needed such that the bias can grow fast enough to
overcome them. For this example we have chosen a stride of 500 steps and a step size of 0.5 kJ/mol. The syntax
in Plumed is:
BEGIN_PLUMED_FILE
OPT_AVERAGED_SGD ...
BIAS=b1
STRIDE=500
LABEL=o1
STEPSIZE=0.5
FES_OUTPUT=100
BIAS_OUTPUT=500
COEFFS_OUTPUT=10
... OPT_AVERAGED_SGD
Now that we have set the scene, we can run our simulation using the run.sh script in the Example1 folder. The
simulation will produce several files:
• COLVAR: Just as in the metadynamics example.
• coeffs.data : Values of the coefficients α and ᾱ .
Generated by Doxygen
604
Additional Modules
• bias..iter- : Bias potential as a function of s at iteration .
• fes..iter- : FES at iteration .
• targetdistribution..data : Target distribution.
You can first observe how the system moves in the CV space in a fashion similar to metadynamics. Then we can
see the evolution of α and ᾱ . The first lines of the file coeffs.data are:
#!
#!
#!
#!
#!
#!
#!
FIELDS idx_d1 b1.coeffs b1.aux_coeffs index
SET time 0.000000
SET iteration 0
SET type LinearBasisSet
SET ndimensions 1
SET ncoeffs_total 11
SET shape_d1 11
0
0.0000000000000000e+00
1
0.0000000000000000e+00
2
0.0000000000000000e+00
3
0.0000000000000000e+00
4
0.0000000000000000e+00
5
0.0000000000000000e+00
6
0.0000000000000000e+00
7
0.0000000000000000e+00
8
0.0000000000000000e+00
9
0.0000000000000000e+00
10
0.0000000000000000e+00
#!-------------------
0.0000000000000000e+00
0.0000000000000000e+00
0.0000000000000000e+00
0.0000000000000000e+00
0.0000000000000000e+00
0.0000000000000000e+00
0.0000000000000000e+00
0.0000000000000000e+00
0.0000000000000000e+00
0.0000000000000000e+00
0.0000000000000000e+00
FIELDS idx_d1 b1.coeffs b1.aux_coeffs index
SET time 10.000000
SET iteration 10
SET type LinearBasisSet
SET ndimensions 1
SET ncoeffs_total 11
SET shape_d1 11
0
0.0000000000000000e+00
0.0000000000000000e+00
1
5.1165453234702052e-01
1.1482045941475065e+00
2
-1.0356798763597277e+00
-1.7365051185667855e+00
3
-5.1830527698835660e-01
-1.1651638070736938e+00
4
4.1754103138162207e-01
4.8203393927719917e-01
5
3.2087945211009694e-01
6.6606116920677805e-01
6
-1.5499943980403830e-01
-4.7946750842365812e-03
7
-1.1433825688016251e-01
-1.5099503286093419e-01
8
9.8787914656136719e-02
1.3156529595420300e-02
9
4.4467081175713474e-03
-8.7160339645570323e-02
10
-1.1504176822089783e-01
-1.5789737594248379e-01
#!-------------------
0
1
2
3
4
5
6
7
8
9
10
#!
#!
#!
#!
#!
#!
#!
0
1
2
3
4
5
6
7
8
9
10
The first column are the coefficient indices, the second are the ᾱ, and the third are the α. Each block in the file
corresponds to a different iteration, in this case iteration 0 and 10. We can plot the evolution of the coefficients using
the gnuplot script plotCoeffs.gpi . The output should be similar to the next figure.
The α change fast and oscillate around some mean value. The ᾱ evolve smoothly until they stabilize around some
equilibrium value. It is important to remember that the bias is a function of ᾱ and since these evolve smoothly, so
will the bias. Once that the ᾱ have stabilized, the simulation can be considered converged.
It is also interesting to observe how the estimation of the FES evolves in time. For this we will plot the FES using
the files fes.b1.iter-. There is a gnuplot script plotFes.gpi that you can use for this purpose. At
variance with metadynamics, in this case there is no growing offset in the bias and therefore we will have to shift the
FES ourselves to distinguish several FES at different times in the same plot.
We can also calculate the height of the barrier as we did in the metadynamics tutorial. The files for carrying out this
task can be found in the Barrier_calculation folder. Remember that the accuracy of this calculation is limited by the
fact that we have chosen a small order in the basis set expansion. We will discuss this aspect in greater detail in
the next example.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
8.6.7.3.4.3
605
Example 2: Target distributions and basis sets
In this example we will consider other choices of target distributions and we will understand the influence of the order
of the basis set expansion. The files needed for this example are contained in the directory Example2. Instead of
introducing a barrier as done in the example above, in this case we will use a uniform target distribution in the
interval [0.23:0.6] nm and decaying to zero in the interval [0.6:0.8] nm. The expression is:
p(s) = { 1C if s < s0
1 − (s−s20 )2
e 2σ if s > s0
C
where s0 = 0.6 nm and σ = 0.05. To define this p(s) in Plumed the input is:
BEGIN_PLUMED_FILE
td1: TD_UNIFORM MINIMA=0.23 MAXIMA=0.6 SIGMA_MAXIMA=0.05
VES_LINEAR_EXPANSION ...
ARG=d1
BASIS_FUNCTIONS=bf1
LABEL=b1
TEMP=300.0
GRID_BINS=300
TARGET_DISTRIBUTION=td1
... VES_LINEAR_EXPANSION
We will choose a basis set of order 20 to be able to capture the features of the FES with detail. If you are doing this
example in a group, each member of the group can choose a different order in the expansion, for instance 5, 10,
20, and 40. The syntax in Plumed is:
BEGIN_PLUMED_FILE
BF_LEGENDRE ...
ORDER=20
MINIMUM=0.23
MAXIMUM=0.8
LABEL=bf1
... BF_LEGENDRE
Once that you start running the simulation, a file named targetdist.b1.data will be created. This file contains the
chosen target distribution. We can plot it to confirm that it is what we are looking for. There is a gnuplot script
plotTargetDistrib.gpi that creates the following plot.
As the simulation runs, it is useful to control the evolution of the coefficients using the gnuplot script plotCoeffs.gpi.
The FES is calculated from the expression:
F (s) = −V (s) −
(s − s0 )2
1
log p(s) = { − V (s) if s < s0 − V (s) +
if s > s0
β
2βσ 2
In other words the bias potential is forced to create the upper barrier that we were explicitly introducing in the first
example. When the FES is calculated the effect of the barrier is "subtracted" through p(s) and therefore the FES
that we calculate does not include the barrier. This can be seen by plotting the fes.b1.iter- files
with gnuplot, for instance:
pl "./fes.b1.iter-10000.data" u 1:2 w l
This plot should be similar to the next figure.
Only the interval [0.23:0.7] is plotted since there is little sampling in the region [0.7:0.8] due to the small value of
p(s) in this region. As discussed before, if there is no sampling, it is not possible to obtain free energies.
When the simulation ends, it is interesting to check if in fact the sampled biased distribution is equal to the chosen
target distribution. The scripts to calculate the sampled biased distribution are located in the directory Biased←Distribution. As usual, we will disregard the initial part of the simulation since in this period the bias is changing a
lot. As done before, we get rid of the first 2 ns of simulation using sed:
Generated by Doxygen
606
Additional Modules
sed ’2,10000d’ ../COLVAR > COLVAR
Once that the coefficients in the expansion have stabilized it is possible to calculate the biased distribution of CVs by
constructing a histogram with equal weights for all points. This distribution should be equal to the target distribution
p(s). The histogram can be calculated in plumed using the following input in the plumed.dat file:
BEGIN_PLUMED_FILE
distance: READ FILE=COLVAR
IGNORE_TIME VALUES=d1
HISTOGRAM ...
ARG=distance
GRID_MIN=0.2
GRID_MAX=0.8
GRID_BIN=100
BANDWIDTH=0.004
LABEL=hh1
... HISTOGRAM
DUMPGRID GRID=hh1 FILE=histo FMT=%24.16e
and running (or using the run.sh script):
plumed --no-mpi driver --plumed plumed.dat --noatoms > plumed.out
The next plot shows that in fact the sampled distribution agrees with the target distribution.
Once that the coefficients are stabilized it is possible to reweight using the standard umbrella sampling formula [92]
. In this case the weight assigned to each configuration is:
w(R) ∝ eβV (s) .
The files needed for this reweighting are contained in the folder ReweightDistance. The procedure to the the
reweighting and plot the results is similar to the ones in the cases above and therefore it is not described in detail.
The reweighted FES is plotted in the next figure and compared to the FES calculated from the formula V (s) =
−F (s) − β1 log p(s).
The two curves do not differ much since the order of the expansion was relatively large. What happens if you chose
a lower or higher order in the expansion?
8.6.7.3.4.4
Restarting a simulation
In this section we will restart the simulation that we have performed in our second example. In directory Example2,
cd to the folder Restart. To restart the simulation we will need:
• LAMMPS restart file, since it stores the last configuration
• COLVAR file, since new lines will be appended
• coeff.data file, containing the iteration number and the values of the coefficients.
Therefore we execute in the command line the following commands:
cp ../restart .
cp ../COLVAR .
cp ../coeffs.data .
In order to restart, the RESTART keyword must be added at the beginning of the input file for PLUMED named
plumed.restart.dat:
RESTART
d1:
.
.
.
DISTANCE ATOMS=319,320
Then the simulation can be restarted using the script runRestart.sh . Check that the output of the new simulation is
appended to the COLVAR file, that the starting time of the new simulation is the ending time of the old simulation,
that CV values are coherent, and that coefficients evolve continuously.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
8.6.7.3.4.5
607
Gaussian target distribution
As an exercise, you can use a target distribution consisting in a gaussian centered at the dissociation barrier. The
syntax in Plumed is:
BEGIN_PLUMED_FILE
td1: TD_GAUSSIAN CENTER1=0.325 SIGMA1=0.03
VES_LINEAR_EXPANSION ...
ARG=d1
BASIS_FUNCTIONS=bf1
LABEL=b1
TEMP=300.0
GRID_BINS=300
TARGET_DISTRIBUTION=td1
... VES_LINEAR_EXPANSION
Gaussian target distributions are useful to focus the sampling on a particular region of CV space. This has been
used in protein folding problems to focus the sampling on the small but relevant folded state [93].
8.6.7.3.4.6
Optimization algorithm
We suggest an exercise to gain experience in choosing the parameters of the optimization algorithm. The averaged
stochastic gradient descent algorithm has two parameters: the stride and the step size. Normally a stride of around
500-2000 steps is used. However it is not always easy to choose the step size. Luckily, the algorithm is quite robust
and will work for different step sizes.
Run different simulation using step sizes µ = 0.001 and µ = 10 and try to rationalize the behavior. Normally, when
the step size is too large, the system gets stuck in CV space and coefficients oscillate wildly. When the step size is
too small, the algorithm runs out of "steam" too fast and the simulation converges slowly. These two extreme cases
should be avoided.
8.6.7.3.5
Final remarks
The purpose of this first tutorial was to introduce the student to VES. At this point one can see that VES is a
powerful and versatile enhanced sampling method. We suggest to explore different possibilities of basis sets and
target distributions. It is also interesting to experiment with different optimization algorithms and parameters of
these.
The next tutorial will deal with the use of the well-tempered target distribution and the construction of biases on 2
CVs.
8.6.7.4
8.6.7.4.1
MARVEL-VES tutorial (Lugano Feb 2017): VES 2
Learning Outcomes
Once this tutorial is completed students will learn to:
• Use the well-tempered target distribution and understand its usefulness
• Construct biases in 1 and 2 dimensions.
Generated by Doxygen
608
Additional Modules
8.6.7.4.2
Resources
The tarball for this project contains the following folders:
• Example1 : Contains the input file for the the first example.
• Example2 : Contains the input file for the the second example.
8.6.7.4.3
Summary of theory
One of the most useful target distribution is the well-tempered one. The well-tempered target distribution is [87] :
p(s) = R
e−(β/γ)F (s)
ds e−(β/γ)F (s)
where γ is the so-called bias factor. It is possible to show that:
p(s) = R
[P (s)]1/γ
ds [P (s)]1/γ
where P (s) is the unbiased distribution of CVs. Therefore the target distribution is the unbiased distribution with
enhanced fluctuations and lowered barriers. This is the same distribution as sampled in well-tempered metadynamics. The advantages of this distribution are that the features of the FES (metastable states) are preserved and
that the system is not forced to sample regions of high free energy as it would if we had chosen the uniform target
distribution. This is specially important when biasing 2 CVs and there are large regions of very high free energy and
therefore they represent un-physical configurations.
There is a caveat though, p(s) depends on F (s) that is the function that we are trying to calculate. One way to
approach this problem is to calculate p(s) self-consistently [87], for instance at iteration k :
(k+1)
p
(k+1)
(s)
e−(β/γ)F
(s) = R
(k+1)
(s)
ds e−(β/γ)F
where:
F (k+1) (s) = −V (k) (s) −
1
log p(k) (s)
β
Normally p(0) (s) is taken to be uniform. Therefore the target distribution evolves in time until it becomes stationary
when the simulation has converged. It has been shown that in some cases the convergence is faster using the
well-tempered target distribution than using the uniform p(s) [87].
8.6.7.4.4
8.6.7.4.4.1
Instructions
The system
We will consider the same system employed in previous tutorials.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
8.6.7.4.4.2
609
Example 1: Enhancing fluctuations
We consider Example 2 of the VES 1 tutorial. In that case we used a uniform target distribution that at some value
decayed to zero. In this case we will use a product of two distributions:
p(s) = R
pWT (s) pbarrier (s)
ds pWT (s) pbarrier (s)
where pWT (s) is the well-tempered target distribution and:
pbarrier (s) = { 1C if s < s0
1 − (s−s20 )2
e 2σ if s > s0
C
with C a normalization factor. The files needed for this exercise are in the directory Example1. This target distribution
can be specified in plumed using:
BEGIN_PLUMED_FILE
td_uniform: TD_UNIFORM MINIMA=0.23 MAXIMA=0.6 SIGMA_MAXIMA=0.05
td_welltemp: TD_WELLTEMPERED BIASFACTOR=5
td_combination: TD_PRODUCT_COMBINATION DISTRIBUTIONS=td_uniform,td_welltemp
VES_LINEAR_EXPANSION ...
ARG=d1
BASIS_FUNCTIONS=bf1
LABEL=b1
TEMP=300.0
GRID_BINS=300
TARGET_DISTRIBUTION=td_combination
... VES_LINEAR_EXPANSION
As usual, we run the example using the run.sh script. As the simulation progresses we can track the evolution of the
target distribution. At variance with previous simulations where p(s) was stationary, in this case it evolves in time.
The p(s) is dumped every 500 steps in a file named targetdist.b1.iter-.data. You can plot these
files manually or using the script plotTargetDistrib.gpi. The result should be similar to the following plot where the
distribution at different times has been shifted to see more clearly the difference.
To shed some light on the nature of the well-tempered target distribution, we will compare the unbiased and biased
distribution of CVs. The unbiased distribution of CVs P (s) is calculated by constructing a histogram of the CVs with
weights given by:
w(R) ∝ eβV (s) .
The biased distribution of CVs p0 (s) is calculated also by constructing a histogram of the CVs but in this case each
point is assigned equal weights. The prime is added in p0 (s) to distinguish the biased distribution from the target
distribution p(s). If the simulation has converged then p0 (s) = p(s). The files needed for this calculation are located
in the Reweight directory. Since this simulation converges fast as compared to previous ones, we only disregard the
first 1 ns of simulation:
sed ’2,5000d’ ../COLVAR > COLVAR
To calculate the biased and unbiased distribution of CVs we use the following PLUMED input:
BEGIN_PLUMED_FILE
distance:
READ FILE=COLVAR IGNORE_TIME VALUES=d1
ves:
READ FILE=COLVAR IGNORE_TIME VALUES=b1.bias
weights: REWEIGHT_BIAS TEMP=300 ARG=ves.bias
HISTOGRAM ...
ARG=distance
GRID_MIN=0.23
GRID_MAX=0.8
GRID_BIN=301
BANDWIDTH=0.006
LABEL=hh1
Generated by Doxygen
610
Additional Modules
... HISTOGRAM
HISTOGRAM ...
ARG=distance
GRID_MIN=0.23
GRID_MAX=0.8
GRID_BIN=301
BANDWIDTH=0.006
LOGWEIGHTS=weights
LABEL=hh2
... HISTOGRAM
DUMPGRID GRID=hh1 FILE=histo_biased FMT=%24.16e
DUMPGRID GRID=hh2 FILE=histo_unbiased FMT=%24.16e
If you do not understand what this input does, you might want to read once again the previous tutorials. The
histograms histo_biased and histo_unbiased correspond to p0 (s) and P (s) , respectively. We are interested in
comparing the unbiased distribution of CVs P (s) and the well-tempered distribution pWT (s). We know from the
equations above that:
pWT (s) ∝ [P (s)]1/γ ,
and also,
pWT (s) ∝ p(s)/pbarrier (s) ∝ p0 (s)/pbarrier (s).
Therefore we have two ways to calculate the well-tempered target distribution. We can compare P (s) and the
well-tempered target distribution calculated in two ways with the following gnuplot lines:
biasFactor=5.
invBiasFactor=1./biasFactor
pl "./histo_unbiased" u 1:(-log($2)) w l title "P(s)"
repl "./histo_unbiased" u 1:(-log($2**invBiasFactor)) w l title "[P(s)]^(1/gamma)"
repl "< paste ./histo_biased ../targetdist.b1.iter-0.data" u 1:(-log($2/$5)) w l title "Sampled p(s)"
There is also a gnuplot script plot.gpi that should do everything for you. The output should be similar to the next plot
where we plot the negative logarithm of the distributions.
Notice that as expected both equations to calculate pWT (s) agree. Also the association barrier of 5 kB T becomes
of 1 kB T when the well-tempered target distribution is sampled.
The take home message of this tutorial is that when the well-tempered target distribution is employed, the biased
distribution of CVs preserves all the features of the unbiased distribution, but barriers are lowered. Equivalently one
may say that fluctuations are enhanced.
8.6.7.4.4.3
Example 2: Constructing a 2 dimensional bias
In this example we will construct a 2 dimensional bias on the distance Na-Cl and the coordination number of Na
with respect to O. The files to run this example are included in the Example2 folder. Two dimensional biases in VES
can be written:
X
V (s1 , s2 ; α) =
αi1 ,i2 fi1 (s1 ) fi2 (s2 ),
i1 ,i2
where fi1 (s1 ) and fi2 (s2 ) are the basis functions. We will choose to expand the bias potential in Legendre polynomials up to order 20 in both dimensions.
BEGIN_PLUMED_FILE
# CV1
BF_LEGENDRE ...
ORDER=20
MINIMUM=0.23
MAXIMUM=0.8
LABEL=bf1
... BF_LEGENDRE
# CV2
BF_LEGENDRE ...
ORDER=20
MINIMUM=2.5
MAXIMUM=7.5
LABEL=bf2
... BF_LEGENDRE
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
611
We have chosen the interval [0.23,0.8] nm for the distance and [2.5,7.5] for the coordination number. The total
number of non-zero coefficients will be 400. In the coefficients file the indices i1 and i2 are given by the first two
columns. We use the well-tempered target distribution together with a barrier at 0.6 nm on the distance Na-Cl.
BEGIN_PLUMED_FILE
td_uniform: TD_UNIFORM MINIMA=0.2,2.5 MAXIMA=0.6,7.5 SIGMA_MAXIMA=0.05,0.0
td_welltemp: TD_WELLTEMPERED BIASFACTOR=5
td_combination: TD_PRODUCT_COMBINATION DISTRIBUTIONS=td_uniform,td_welltemp
VES_LINEAR_EXPANSION ...
ARG=d1,coord
BASIS_FUNCTIONS=bf1,bf2
LABEL=b1
TEMP=300.0
GRID_BINS=300,300
TARGET_DISTRIBUTION=td_combination
... VES_LINEAR_EXPANSION
We can now run the simulation and control its progress. Since there are 400 coefficients we choose the largest (in
absolute value) to control the convergence of the simulation. In this case we have chosen coefficients with indices
(i1 , i2 ) as (1,0), (0,1), (1,1), (2,1), and (0,2). You can plot the evolution of the coefficients using the gnuplot script
plotCoeffs.gpi. This plot should look similar to the following one. The bias therefore converges smoothly as in one
dimensional problems.
The estimated FES can also be plotted to control the progress of the simulation. For instance in gnuplot,
set xr [0.23:0.7]
set yr [3:7]
set zr [0:6]
set cbr [0:6]
set pm3d map
temp=2.494
spl "./fes.b1.iter-1000.data" u 1:2:($3/temp) w pm3d notitle
There is a gnuplot script plotFes.gpi that generates the following plot for the FES after 10 ns of simulation:
This FES agrees with that calculated through reweighting in the metadynamics tutorial.
As an exercise, you can repeat this simulation using the uniform target distribution instead of the well-tempered
p(s). Compare the convergence time of both simulations. Discuss the reasons why the algorithm converges faster
to the well-tempered target distribution than to the uniform one. Does it make sense to sample all the CV space
uniformly?
8.6.7.4.5
Final remarks
At this point the student has acquired experience with several characteristics of the VES method. There is one tool
that has proven to be instrumental for many problems and that has not yet been discussed in this series of tutorials:
the use of multiple walkers. This tool will be the subject of another tutorial.
8.6.7.5
8.6.7.5.1
MARVEL-VES tutorial (Lugano Feb 2017): Kinetics
Aims
The aim of this tutorial is to introduce the use of VES for obtaining kinetic information of activated processes. We will
learn how to set up a biased simulation using a fixed flooding potential acting on a relevant slow degree of freedom.
We can then scale the accelerated MD time in a post-processing procedure.
Generated by Doxygen
612
Additional Modules
8.6.7.5.2
Learning Outcomes
Once this tutorial is completed students will:
• Optimize a bias using VES with an energy cutoff to selectively fill low regions of the free energy surface.
• Use the optimized bias to observe several rare event transitions
• Post-process the accelerated trajectory to obtain an unbiased estimate of the transition rate
• Compute the empirical cumulative distribution of first passage times and compare to a theoretical model.
8.6.7.5.3
Resources
The tarball for this project contains the following files:
• CH.airebo : Force field parameters for LAMMPS
• input : LAMMPS input script
• data.start : Starting configuration in LAMMPS format
• plumed.dat : Example PLUMED file
• time-reweighting.py : Python script for post-processing trajectory
• TRAJECTORIES-1700K : A directory containing many trajectories for post processing
• get-all-fpt.py : A python script to extract transition times from the trajectories
• cdf.analysis.py : A python script to compute the cumulative probability distribution and perform KS test
8.6.7.5.4
Requirements
• python with numpy, scipy, and statsmodels
• LAMMPS compiled with MANYBODY package
• VMD for visualization
8.6.7.5.5
8.6.7.5.5.1
Instructions
Exercise 1A. Preliminary investigation using VES
As an example of an activated process in materials science, we will work with the Stone-Wales transformation in a
carbon nanotube. The tarball for this project contains the inputs necessary to run a simulation in LAMMPS for
a 480 atom carbon nanotube. We use the AIREBO (Adaptive Intermolecular Reactive Empirical Bond Order) force
field parameters which can approximately describe C-C bond breakage and formation at reasonable computational
cost. For CVs we can use the coordination number in PLUMED to measure the number of covalent bonds among
different groups of atoms. The transformation involves breaking two C-C bonds and forming two alternative C-C
bonds.A definition of these CVs as well as the relevant C-C bonds are depicted in Figure stone-wales. We prepare
a PLUMED input file as follows.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
613
BEGIN_PLUMED_FILE
# set distance units to angstrom, time to ps, and energy to eV
UNITS LENGTH=A TIME=ps ENERGY=eV
# define two variables
COORDINATION GROUPA=229,219 GROUPB=238,207 R_0=1.8 NN=8 MM=16 PAIR LABEL=CV1
COORDINATION GROUPA=229,219 GROUPB=207,238 R_0=1.8 NN=8 MM=16 PAIR LABEL=CV2
# the difference between variables
COMBINE ARG=CV1,CV2 COEFFICIENTS=1,-1 POWERS=1,1 LABEL=d1 PERIODIC=NO
In the above, the first line sets the energy units. The second and third line define the two CVs for the C-C covalent
bonds. (We have chosen atoms 238,207,229 and 219; however this choice is arbitrary and other atoms could
equally well have been chosen.) Lastly, we define a simple approximate reaction coordinate given by the difference
between CV1 and CV2 that we can use to monitor the transition.
Next we will use VES to drive the transformation at 1700 K. We bias the formation of bonds DB and AC shown
in Figure stone-wales using CV2 which changes from 0 to 2 during the transformation. (Although a more rigorous
treatment would bias both CVs, for this tutorial we will simplify things and work in only one dimension). We choose
a Chebyshev polynomial basis set up to order 36
BEGIN_PLUMED_FILE
# The basis set to use
bf1: BF_CHEBYSHEV ORDER=36 MINIMUM=0.0 MAXIMUM=2.0
and we tell PLUMED to use VES acting on CV2 with a free energy cutoff
BEGIN_PLUMED_FILE
td_uniform: TD_UNIFORM
VES_LINEAR_EXPANSION ...
ARG=CV2
BASIS_FUNCTIONS=bf1
LABEL=variational
TEMP=1700
BIAS_CUTOFF=15.0
BIAS_CUTOFF_FERMI_LAMBDA=10.0
TARGET_DISTRIBUTION=td_uniform
... VES_LINEAR_EXPANSION
Here we are biasing CV2 with the basis set defined above. The final two lines impose the cutoff at 15 eV. The cutoff
is of the form
1
1 + eλ[F (s)−Fc ]
where λ (inverse energy units) controls how sharply the function goes to zero. Above we have set λ = 10.0 to
ensure the cutoff goes sharply enough to zero.
The following input updates the VES bias every 200 steps, writing out the bias every 10 iterations. To enforce the
energy cutoff we also need to update the target distribution which we do every 40 iterations with the TARGETDI←ST_STRIDE flag.
BEGIN_PLUMED_FILE
OPT_AVERAGED_SGD ...
BIAS=variational
STRIDE=200
LABEL=var-S
STEPSIZE=0.1
COEFFS_FILE=coeffs.dat
BIAS_OUTPUT=10
TARGETDIST_STRIDE=40
TARGETDIST_OUTPUT=40
COEFFS_OUTPUT=1
... OPT_AVERAGED_SGD
Generated by Doxygen
614
Additional Modules
Finally, we will stop the simulation when the transition occurs using the COMMITTOR in PLUMED
BEGIN_PLUMED_FILE
COMMITTOR ARG=d1 BASIN_LL1=-2.0 BASIN_UL1=-1.0 STRIDE=600
Run the simulation using LAMMPS
lmp_mpi < input
and plot the last few bias output files (bias.variational.iter-n.data) using gnuplot. What is the difference between the
maximum and minimum values of the bias obtained during the simulation? Is the cutoff value sufficient to cross the
barrier? Is the cutoff value too large?
Figure Figure1A shows an example bias potential after 90 iterations. Note that a cutoff of 15 eV is too large as the
system transitions before the bias reaches the prescribed cutoff. From Figure Figure1A we see a barrier height of
approximately 7.3 eV.
The output also produces an movie.xyz file which can be viewed in vmd. For better visualization, first change atom
id from 1 to C by typing
sed "s/^1 /C /" movie.xyz > newmovie.xyz
Then load the newmovie.xyz into vmd and choose Graphics –> Representations and set Drawing Method to
DynamicBonds. Create a second representation by clicking Create Rep and set the Drawing Method to VDW.
Change the sphere scale to 0.3 and play the movie. You should observe the Stone-Wales transformation right
before the end of the trajectory.
8.6.7.5.5.2
Exercise 1B. Set up and run a VES bias imposing a cutoff
In this exercise we will run a VES simulation to fill the FES only up to a certain cutoff. This will be the first step in
order to obtain kinetic information from biased simulations. In the previous section, we observed that a cutoff of 15
eV is too strong for our purpose. Change the cutoff energy from 15.0 to 6.0 eV by setting
BIAS_CUTOFF=6.0
and rerun the simulation from Exercise 1A. [Note: In practice one can use multiple walkers during the optimization
by adding the flag MULTIPLE_WALKERS]
Plot some of the bias files (bias.variational.iter-n.data) that are printed during the simulation using gnuplot. At the
end of the simulation, you should be able to reproduce something like Figure Figure1B. Is the bias converging? If
so, how many iterations does it require to converge?
Figure Figure1B shows the bias potential after 70,80, and 90 iteration steps. Note that the bias has reached the
cutoff and goes to zero at around 1 Angstrom.
Generated by Doxygen
8.6 Variationally Enhanced Sampling (VES code)
8.6.7.5.5.3
615
Exercise 2. Using a fixed bias as a flooding potential to obtain rates
In this exercise we will use the bias obtained above as a static umbrella potential. We will set up and run a new
trajectory to measure the first passage time of escape from the well.
We can extract the coefficients that we need from the final iteration in Exercise-1B above.
tail -n 47 coeffs.dat > fixed-coeffs.dat
Now create a new directory from which you will run a new simulation and copy the necessary input files (including
the fixed-coeffs.dat) into this directory. Modify the PLUMED file so that the optimized coefficients are read by the
VES_LINEAR_EXPANSION
BEGIN_PLUMED_FILE
td_uniform: TD_UNIFORM
VES_LINEAR_EXPANSION ...
ARG=CV2
BASIS_FUNCTIONS=bf1
LABEL=variational
TEMP=1700
BIAS_CUTOFF=6.0
BIAS_CUTOFF_FERMI_LAMBDA=10.0
TARGET_DISTRIBUTION=td_uniform
COEFFS=fixed-coeffs.dat
... VES_LINEAR_EXPANSION
The final line specifies the coefficients to be read from a file.
Make sure to remove the lines for the stochastic optimization (OPT_AVERAGED_SGD) as we no longer wish to
update the bias.
We will also perform metadynamics with an infrequent deposition stride to ensure that the trajectory does not get
stuck in any regions where the bias potential is not fully converged The following implements metadynamics on both
CV1 and CV2 with a deposition stride of 4000 steps and a hill height of 0.15 eV.
BEGIN_PLUMED_FILE
METAD ...
ARG=CV1,CV2
SIGMA=0.2,0.2
HEIGHT=0.15
PACE=4000
LABEL=metad
... METAD
Again we will use the COMMITTOR to stop the trajectory after the transition.
BEGIN_PLUMED_FILE
COMMITTOR ARG=d1 BASIN_LL1=-2.0 BASIN_UL1=-1.0
Now run a trajectory with the fixed bias. What is the time (biased) to escape? Plot the trajectory of the approximate
reaction coordinate (column 4 in the COLVAR) in gnuplot. An example is shown in Figure Figure2.
Also look at the metadynamics bias in the column labeled metad.bias. How does the magnitude compare to the
bias from VES in column variational.bias?
The crossing time for a single event doesn't tell us much because we don't have any statistics on the transition
events. To obtain the mean first passage time, we have to repeat the calculation many times. To generate statistically
independent samples, we have to change the seed for the random velocities that are generated in the LAMMPS
input file. In a new directory, copy the necessary files and edit the following line in the input file
velocity
all create 1700.
495920
Choose a different 6 digit random number and repeat Exercise 2. How does the escape time compare to what
you obtained before? Repeat the procedure several times with different velocity seeds to get a distribution of first
passage times. Make sure you launch each simulation from a separate directory and keep all COLVAR files as you
will need them in the next section where we will analyze the transition times.
Generated by Doxygen
616
8.6.7.5.5.4
Additional Modules
Exercise 3. Post processing to obtain unbiased estimate for the transition rate
In the previous section you generated several trajectories with different first passage times. However, these times
need to be re-weighted to correct for the bias potential. We can scale the time according to the hyperdynamics
formula
t∗ = ∆tM D
n
X
eβV (s)
i
Note that we need to add the total bias at each step, coming from both the VES bias and metadynamics. The python
script time-reweighting.py will read the COLVAR from Exercise 2 and print the final reweighted time (in seconds).
Open the script to make sure you understand how it works.
Run the script using
python time-reweighting.py
Note that the output first passage time is converted to seconds. What is the acceleration factor of our biased
simulation? (i.e. the ratio of biased to unbiased transition times) The script also produces a time-reweighted
trajectory COLVAR-RW for a specified CV (here we choose the approximate reaction coordinate, d1). Plot the
reweighted COLVAR-RW in gnuplot and compare the original vs. time-reweighted trajectories. In particular, what
effect does rescaling have on the time step?
Rerun the script for each of the trajectories you have run with the fixed bias and compute the mean first passage
time from your data. The Stone-Wales transformation at 1700 K is estimated in fullerene to be ∼10 days. How does
your average time compare to this value?
The distribution of first passage times for an activated processes typically follows an exponential distribution. Instead
of directly making a histogram of the first passage times, we can look at the cumulative distribution function which
maps a value x to the fraction of values less than or equal to x. Since we are computing the cumulative distribution
from a data set, this is called the empirical cumulative distribution (ECDF). On the other hand, the theoretical
cumulative distribution (CDF) of an exponentially distributed random process is
P (t) = 1 − e−t/τ
where τ is the mean first passage time.
In order to calculate the ECDF we need many trajectories. Several COLVAR files are included in the TRAJECT←ORIES-1700K directory. The script get-all-fpt.py is a modified version of time-reweighting.py and will calculate the
first passage time (fpt) from all the simulation data and will output the times to a file fpt.dat. Run the script from the
TRAJECTORIES-1700K directory
python get-all-fpt.py
You should obtain the output file fpt.dat which has a list of all the times. You can append your own values you
obtained from Exercise 2 to the end of the list to increase the number of data points.
The script cdf-analysis.py will compute the ECDF and fit the distribution to the theoretical CDF. The script uses the
statsmodels Python module. Run the script with
python cdf-analyysis.py
from the same directory where the fpt.dat file is located. The script prints both the mean first passage time of the
data as well as the fit parameter τ . How do these two values compare?
Figure Figure3 shows an example fit of the ECDF to the theoretical CDF for a Poisson process. To test the reliability
of the fit, we can generate some data set according the theoretical CDF and perform a two-sample Kolmogorov-←Smirnov (KS) test. The KS test provides the probability that the two sets of data are drawn from the same underlying
distribution expressed in the so-called p-value. The null hypothesis is typically rejected for p-value < 0.05. The script
cdf-analysis.py also performs the KS test and prints the p-value. What is the p-value we obtain from your dataset of
transition times?
Generated by Doxygen
8.7 PIV collective variable
8.7
617
PIV collective variable
Overview
To be completed
Installation
This module is not installed by default. Add '--enable-modules=piv' to your './configure' command when building
PLUMED to enable these features.
Usage
Currently, all features of the PIV module are included in a single PIV collective variable: PIV
Module Contents
• CVs Documentation
8.7.1
CVs Documentation
The following list contains descriptions of biases developed for the PLUMED-PIV module. They can be used in
combination with other actions outside of the PIV module.
PIV
8.7.1.1
Calculates the PIV-distance.
PIV
This is part of the piv module
It is only available if you configure PLUMED with ./configure –enable-modules=piv . Furthermore, this
feature is still being developed so take care when using it and report any problems on the mailing list.
Calculates the PIV-distance.
PIV distance is the squared Cartesian distance between the PIV [94] [95] associated to the configuration of the
system during the dynamics and a reference configuration provided as input (PDB file format). PIV can be used
together with FUNCPATHMSD to define a path in the PIV space.
Compulsory keywords
Generated by Doxygen
618
Additional Modules
SWITCH
The switching functions parameter.You should specify a Switching function for all PIV blocks.←Details of the various switching functions you can use are provided on switchingfunction. You
can use multiple instances of this keyword i.e. SWITCH1, SWITCH2, SWITCH3...
PRECISION
the precision for approximating reals with integers in sorting.
REF_FILE
PIVATOMS
SORT
ATOMTYPES
PDB file name that contains the ith reference structure.
Number of atoms to use for PIV.
Whether to sort or not the PIV block.
The atom types to use for PIV.
Options
NUMERICAL_DERIVATIVES
( default=off ) calculate the derivatives for these quantities numerically
NOPBC
( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) Print the actual and reference PIV and exit
TEST
COM
( default=off ) Use centers of mass of groups of atoms instead of atoms as
specified in the Pdb file
ONLYCROSS
( default=off ) Use only cross-terms (A-B, A-C, B-C, ...) in PIV
ONLYDIRECT
( default=off ) Use only direct-terms (A-A, B-B, C-C, ...) in PIV
DERIVATIVES
( default=off ) Activate the calculation of the PIV for every class (needed for
numerical derivatives).
NLIST
( default=off ) Use a neighbor list for distance calculations.
SERIAL
( default=off ) Perform the calculation in serial - for debug purpose
TIMER
( default=off ) Perform timing analysis on heavy loops.
SFACTOR
Scale the PIV-distance by such block-specific factor
VOLUME
Scale atom-atom distances by the cubic root of the cell volume. The input
volume is used to scale the R_0 value of the switching function.
UPDATEPIV
Frequency (in steps) at which the PIV is updated.
NL_CUTOFF
Neighbor lists cutoff.
NL_STRIDE
Update neighbor lists every NL_STRIDE steps.
NL_SKIN
The maximum atom displacement tolerated for the neighbor lists update.
Examples
The following example calculates PIV-distances from three reference configurations in Ref1.pdb, Ref2.pdb and
Ref3.pdb and prints the results in a file named colvar. Three atoms (PIVATOMS=3) with names (pdb file) A B
and C are used to construct the PIV and all PIV blocks (AA, BB, CC, AB, AC, BC) are considered. SFACT←OR is a scaling factor that multiplies the contribution to the PIV-distance given by the single PIV block. NLIST
sets the use of neighbor lists for calculating atom-atom distances. The SWITCH keyword specifies the parameters
of the switching function that transforms atom-atom distances. SORT=1 means that the PIV block elements are
sorted (SORT=0 no sorting.) Values for SORT, SFACTOR and the neighbor list parameters have to be specified for
each block. The order is the following: AA,BB,CC,AB,AC,BC. If ONLYDIRECT (ONLYCROSS) is used the order is
AA,BB,CC (AB,AC,BC). The sorting operation within each PIV block is performed using the counting sort algorithm,
PRECISION specifies the size of the counting array.
BEGIN_PLUMED_FILE
PIV ...
Generated by Doxygen
8.7 PIV collective variable
619
LABEL=Pivd1
PRECISION=1000
NLIST
REF_FILE=Ref1.pdb
PIVATOMS=3
ATOMTYPES=A,B,C
SFACTOR=0.3,0.5,1.0,0.2,0.2,0.2
SORT=1,1,1,1,1,1
SWITCH1={RATIONAL R_0=0.6 MM=12 NN=4}
SWITCH2={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH3={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH4={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH5={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH6={RATIONAL R_0=0.5 MM=12 NN=6}
NL_CUTOFF=0.8,0.6,0.6,0.7,0.7,0.7
NL_STRIDE=10,10,10,10,10,10
NL_SKIN=0.1,0.1,0.1,0.1,0.1,0.1
... PIV
PIV ...
LABEL=Pivd2
PRECISION=1000
NLIST
REF_FILE=Ref2.pdb
PIVATOMS=3
ATOMTYPES=A,B,C
SFACTOR=0.3,0.5,1.0,0.2,0.2,0.2
SORT=1,1,1,1,1,1
SWITCH1={RATIONAL R_0=0.6 MM=12 NN=4}
SWITCH2={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH3={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH4={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH5={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH6={RATIONAL R_0=0.5 MM=12 NN=6}
NL_CUTOFF=0.8,0.6,0.6,0.7,0.7,0.7
NL_STRIDE=10,10,10,10,10,10
NL_SKIN=0.1,0.1,0.1,0.1,0.1,0.1
... PIV
PIV ...
LABEL=Pivd3
PRECISION=1000
NLIST
REF_FILE=Ref3.pdb
PIVATOMS=3
ATOMTYPES=A,B,C
SFACTOR=0.3,0.5,1.0,0.2,0.2,0.2
SORT=1,1,1,1,1,1
SWITCH1={RATIONAL R_0=0.6 MM=12 NN=4}
SWITCH2={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH3={RATIONAL R_0=0.4 MM=10 NN=5}
SWITCH4={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH5={RATIONAL R_0=0.5 MM=12 NN=6}
SWITCH6={RATIONAL R_0=0.5 MM=12 NN=6}
NL_CUTOFF=0.8,0.6,0.6,0.7,0.7,0.7
NL_STRIDE=10,10,10,10,10,10
NL_SKIN=0.1,0.1,0.1,0.1,0.1,0.1
... PIV
PRINT ARG=Pivd1,Pivd2,Pivd3 FILE=colvar
WARNING: Both the "CRYST" and "ATOM" lines of the PDB files must conform precisely to the official pdb format,
including the width of each alphanumerical field:
CRYST1
ATOM
31.028
36.957
23.143 89.93 92.31
1 OW1 wate
1
15.630 19.750
89.99 P 1
1.520 1.00
1
0.00
In each pdb frame, atoms must be numbered in the same order and with the same element symbol as in the input
of the MD program.
The following example calculates the PIV-distances from two reference configurations Ref1.pdb and Ref2.pdb and
uses PIV-distances to define a Path Collective Variable (FUNCPATHMSD) with only two references (Ref1.pdb and
Generated by Doxygen
620
Additional Modules
Ref2.pdb). With the VOLUME keyword one scales the atom-atom distances by the cubic root of the ratio between
the specified value and the box volume of the initial step of the trajectory file.
BEGIN_PLUMED_FILE
PIV ...
LABEL=c1
PRECISION=1000
VOLUME=12.15
NLIST
REF_FILE=Ref1.pdb
PIVATOMS=2
ATOMTYPES=A,B
ONLYDIRECT
SFACTOR=1.0,0.2
SORT=1,1
SWITCH1={RATIONAL
SWITCH2={RATIONAL
NL_CUTOFF=1.2,1.2
NL_STRIDE=10,10
NL_SKIN=0.1,0.1
... PIV
PIV ...
LABEL=c2
PRECISION=1000
VOLUME=12.15
NLIST
REF_FILE=Ref2.pdb
PIVATOMS=2
ATOMTYPES=A,B
ONLYDIRECT
SFACTOR=1.0,0.2
SORT=1,1
SWITCH1={RATIONAL
SWITCH2={RATIONAL
NL_CUTOFF=1.2,1.2
NL_STRIDE=10,10
NL_SKIN=0.1,0.1
... PIV
R_0=0.6 MM=12 NN=4}
R_0=0.5 MM=10 NN=5}
R_0=0.6 MM=12 NN=4}
R_0=0.4 MM=10 NN=5}
p1: FUNCPATHMSD ARG=c1,c2 LAMBDA=0.180338
METAD ARG=p1.s,p1.z SIGMA=0.01,0.2 HEIGHT=0.8 PACE=500
LABEL=res
PRINT ARG=c1,c2,p1.s,p1.z,res.bias STRIDE=500 FILE=colvar FMT=%15.6f
When using PIV please cite [95] .
(See also PRINT)
Generated by Doxygen
Chapter 9
Command Line Tools
PLUMED contains a number of simple command line tools. To use one of these tools you issue a command
something like:
plumed
The following is a list of the various standalone tools that PLUMED contains.
completion
Dumps the body of a bash function to be used for auto completion.
config
inquire plumed about how it was configure
driver-float
Equivalent to driver, but using single precision reals.
driver
driver is a tool that allows one to to use plumed to post-process an existing trajectory.
gentemplate
gentemplate is a tool that you can use to construct template inputs for the various actions
info
This tool allows you to obtain information about your plumed version
kt
Print out the value of kB T at a particular temperature
manual
manual is a tool that you can use to construct the manual page fora particular action
mklib
compile a .cpp file into a shared library
newcv
create a new collective variable from a template
partial_tempering
create a new collective variable from a template
patch
patch an MD engine
pathtools
pathtools can be used to construct paths from pdb data
pdbrenumber
Modify atom numbers in a PDB, possibly using hybrid-36 coding.
pesmd
Pesmd allows one to do (biased) Langevin dynamics on a two-dimensional potential energy
surface.
simplemd allows one to do molecular dynamics on systems of Lennard-Jones atoms.
simplemd
sum_hills
vim2html
sum_hills is a tool that allows one to to use plumed to post-process an existing hills/colvar
file
convert plumed input file to colored html using vim syntax
In addition to the keywords above, by enabling optional modules you can access to the following keywords:
drr_tool
(from Extended-System Adaptive Biasing Force module) - Extract .grad and .count
files from the binary output .drrstate - Merge windows
ves_md_linearexpansion
(from Variationally Enhanced Sampling (VES code) module) Simple MD code for dynamics on a potential energy surface given by a linear basis set expansion.
622
Command Line Tools
For all these tools and to use PLUMED as a plugin in an MD calculation you will need an input file.
9.1
completion
This is part of the cltools module
Dumps the body of a bash function to be used for auto completion.
Users will typically not need this command. See more at Using bash autocompletion
Options
--help/-h
( default=off ) print this help
Examples
plumed completion
9.2
config
inquire plumed about how it was configure
Note
This command line tool is implemented as a shell script. Its help message is pasted below:
Options:
-h, --help
print this help and exit
-q, --quiet
don’t write anything, just return true of false
show
dump a full configuration file
has [word1 [word2]..]
check if plumed has features words
module [word1 [word2]..]
check if plumed has enables modules words
makefile_conf
dumps the Makefile.conf file
Examples:
Check if
> plumed
Check if
> plumed
Check if
> plumed
9.3
plumed
config
plumed
config
plumed
config
as xdrfile enabled
has xdrfile
as xdrfile AND zlib enabled
has xdrfile zlib
as module colvar active
module colvar
driver-float
Generated by Doxygen
9.3 driver-float
623
This is part of the cltools module
Equivalent to driver, but using single precision reals.
The purpose of this tool is just to test what PLUMED does when linked from a single precision code.
The input trajectory is specified using one of the following
--ixyz
--igro
--ixtc
--itrr
--mf_dcd
--mf_crd
--mf_crdbox
--mf_gro
--mf_g96
--mf_trr
--mf_trj
--mf_xtc
--mf_pdb
the trajectory in xyz format
the trajectory in gro format
the trajectory in xtc format (xdrfile implementation)
the trajectory in trr format (xdrfile implementation)
molfile: the trajectory in dcd format
molfile: the trajectory in crd format
molfile: the trajectory in crdbox format
molfile: the trajectory in gro format
molfile: the trajectory in g96 format
molfile: the trajectory in trr format
molfile: the trajectory in trj format
molfile: the trajectory in xtc format
molfile: the trajectory in pdb format
The following must be present
--plumed
--timestep
( default=plumed.dat ) specify the name of the plumed input file
--trajectory-stride
( default=1 ) the frequency with which frames were output to this trajectory during
the simulation (0 means that the number of the step is read from the trajectory
file, currently working only for xtc/trr files read with –ixtc/–trr)
--multi
( default=0 ) set number of replicas for multi environment (needs MPI)
( default=1.0 ) the timestep that was used in the calculation that produced this
trajectory in picoseconds
The following options are available
--help/-h
--help-debug
--noatoms
( default=off ) print this help
--parse-only
--dump-full-virial
( default=off ) read the plumed input file and stop
--length-units
--mass-units
units for length, either as a string or a number
Generated by Doxygen
( default=off ) print special options that can be used to create regtests
( default=off ) don't read in a trajectory. Just use colvar files as specified in
plumed.dat
( default=off ) with –dump-forces, it dumps the 9 components of the virial
units for mass in pdb and mc file, either as a string or a number
624
Command Line Tools
--charge-units
--kt
--dump-forces
--dump-forces-fmt
--pdb
--mc
--box
--natoms
--initial-step
--debug-forces
units for charge in pdb and mc file, either as a string or a number
set kB T , it will not be necessary to specify temperature in input file
dump the forces on a file
( default=%f ) the format to use to dump the forces
provides a pdb with masses and charges
provides a file with masses and charges as produced with DUMPMASSCHARGE
comma-separated box dimensions (3 for orthorhombic, 9 for generic)
provides number of atoms - only used if file format does not contain number of
atoms
provides a number for the initial step, default is 0
output a file containing the forces due to the bias evaluated using numerical
derivatives and using the analytical derivatives implemented in plumed
Examples
plumed driver-float --plumed plumed.dat --ixyz trajectory.xyz
See also examples in driver
9.4
driver
This is part of the cltools module
driver is a tool that allows one to to use plumed to post-process an existing trajectory.
The input to driver is specified using the command line arguments described below.
In addition, you can use the special READ command inside your plumed input to read in colvar files that were
generated during your MD simulation. The values read in can then be treated like calculated colvars.
Warning
Notice that by default the driver has no knowledge about the masses and charges of your atoms! Thus, if you
want to compute quantities depending charges (e.g. DHENERGY) or masses (e.g. COM) you should pass
the proper information to the driver. You can do it either with the –pdb option or with the –mc option. The latter
will read a file produced by DUMPMASSCHARGE .
The input trajectory is specified using one of the following
--ixyz
--igro
--ixtc
--itrr
--mf_dcd
--mf_crd
the trajectory in xyz format
the trajectory in gro format
the trajectory in xtc format (xdrfile implementation)
the trajectory in trr format (xdrfile implementation)
molfile: the trajectory in dcd format
molfile: the trajectory in crd format
Generated by Doxygen
9.4 driver
625
--mf_crdbox
--mf_gro
--mf_g96
--mf_trr
--mf_trj
--mf_xtc
--mf_pdb
molfile: the trajectory in crdbox format
molfile: the trajectory in gro format
molfile: the trajectory in g96 format
molfile: the trajectory in trr format
molfile: the trajectory in trj format
molfile: the trajectory in xtc format
molfile: the trajectory in pdb format
The following must be present
--plumed
--timestep
( default=plumed.dat ) specify the name of the plumed input file
--trajectory-stride
( default=1 ) the frequency with which frames were output to this trajectory during
the simulation (0 means that the number of the step is read from the trajectory
file, currently working only for xtc/trr files read with –ixtc/–trr)
--multi
( default=0 ) set number of replicas for multi environment (needs MPI)
( default=1.0 ) the timestep that was used in the calculation that produced this
trajectory in picoseconds
The following options are available
--help/-h
--help-debug
--noatoms
( default=off ) print this help
--parse-only
--dump-full-virial
( default=off ) read the plumed input file and stop
--length-units
--mass-units
--charge-units
--kt
--dump-forces
--dump-forces-fmt
--pdb
--mc
--box
--natoms
units for length, either as a string or a number
--initial-step
--debug-forces
( default=off ) print special options that can be used to create regtests
( default=off ) don't read in a trajectory. Just use colvar files as specified in
plumed.dat
( default=off ) with –dump-forces, it dumps the 9 components of the virial
units for mass in pdb and mc file, either as a string or a number
units for charge in pdb and mc file, either as a string or a number
set kB T , it will not be necessary to specify temperature in input file
dump the forces on a file
( default=%f ) the format to use to dump the forces
provides a pdb with masses and charges
provides a file with masses and charges as produced with DUMPMASSCHARGE
comma-separated box dimensions (3 for orthorhombic, 9 for generic)
provides number of atoms - only used if file format does not contain number of
atoms
provides a number for the initial step, default is 0
output a file containing the forces due to the bias evaluated using numerical
derivatives and using the analytical derivatives implemented in plumed
Examples
The following command tells plumed to post process the trajectory contained in trajectory.xyz by performing
Generated by Doxygen
626
Command Line Tools
the actions described in the input file plumed.dat. If an action that takes the stride keyword is given a stride
equal to n then it will be performed only on every nth frames in the trajectory file.
plumed driver --plumed plumed.dat --ixyz trajectory.xyz
Notice that xyz files are expected to be in internal PLUMED units, that is by default nm. You can change this
behavior by using the --length-units option:
plumed driver --plumed plumed.dat --ixyz trajectory.xyz --length-units A
The strings accepted by the --length-units options are the same ones accepted by the UNITS action. Other
file formats typically have their default coordinates (e.g., gro files are always in nm) and it thus should not be
necessary to use the --length-units option. Additionally, consider that the units used by the driver might
be different by the units used in the PLUMED input file plumed.dat. For instance consider the command:
plumed driver --plumed plumed.dat --ixyz trajectory.xyz --length-units A
where plumed.dat is
BEGIN_PLUMED_FILE
# no explicit UNITS action here
d: DISTANCE ATOMS=1,2
PRINT ARG=d FILE=colvar
In this case, the driver reads the xyz file assuming it to contain coordinates in Angstrom units. However, the
resulting colvar file contains a distance expressed in nm.
The following command tells plumed to post process the trajectory contained in trajectory.xyz. by performing the
actions described in the input file plumed.dat.
plumed driver --plumed plumed.dat --ixyz trajectory.xyz --trajectory-stride 100 --timestep 0.001
Here though --trajectory-stride is set equal to the frequency with which frames were output during the
trajectory and the --timestep is equal to the simulation timestep. As such the STRIDE parameters in the
plumed.dat files are referred to the original timestep and any files output resemble those that would have been
generated had we run the calculation we are running with driver when the MD simulation was running.
PLUMED can read xyz files (in PLUMED units) and gro files (in nm). In addition, PLUMED includes by default
support for a subset of the trajectory file formats supported by VMD, e.g. xtc and dcd:
plumed driver --plumed plumed.dat --pdb diala.pdb --mf_xtc traj.xtc --trajectory-stride 100 --timestep 0.001
where --mf_ prefixes the extension of one of the accepted molfile plugin format. If PLUMED has been installed
with full molfile support, other formats will be available. Just type plumed driver --help to see which plugins
are available.
Molfile plugin require periodic cell to be triangular (i.e. first vector oriented along x and second vector in xy plane).
This is true for many MD codes. However, it could be false if you rotate the coordinates in your trajectory before
reading them in the driver. Also notice that some formats (e.g. amber crd) do not specify atom number. In this case
you can use the --natoms option:
plumed driver --plumed plumed.dat --imf_crd trajectory.crd --natoms 128
Check the available molfile plugins and limitations at this link.
Additionally, you can use the xdrfile implementation of xtc and trr. To this aim, just download and install properly the
xdrfile library (see this link). If the xdrfile library is installed properly the PLUMED configure script should be
able to detect it and enable it. Notice that the xdrfile implementation of xtc and trr is more robust than the molfile
one, since it provides support for generic cell shapes. In addition, it allows DUMPATOMS to write compressed xtc
files.
9.4.1
READ
Generated by Doxygen
9.4 driver
627
This is part of the generic module
Read quantities from a colvar file.
This Action can be used with driver to read in a colvar file that was generated during an MD simulation
Description of components
The READ command will read those fields that are labelled with the text string given to the VALUE keyword. It will
also read in any fields that are labeled with the text string given to the VALUE keyword followed by a dot and a
further string. If a single Value is read in this value can be referenced using the label of the Action. Alternatively,
if multiple quantities are read in, they can be referenced elsewhere in the input by using the label for the Action
followed by a dot and the character string that appeared after the dot in the title of the field.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which the file should be read.
EVERY
( default=1 ) only read every nth line of the colvar file. This should be used if the colvar was written
more frequently than the trajectory.
VALUES
FILE
the values to read from the file
the name of the file from which to read these quantities
Options
IGNORE_TIME
( default=off ) ignore the time in the colvar file. When this flag is not present read will be
quite strict about the start time of the simulation and the stride between frames
IGNORE_FORCES
( default=off ) use this flag if the forces added by any bias can be safely ignored. As
an example forces can be safely ignored if you are doing post processing that does not
involve outputting forces
UPDATE_FROM
Only update this action from this time
UPDATE_UNTIL
Only update this action until this time
Examples
This input reads in data from a file called input_colvar.data that was generated in a calculation that involved PLU←MED. The first command reads in the data from the column headed phi1 while the second reads in the data from
the column headed phi2.
BEGIN_PLUMED_FILE
rphi1:
READ FILE=input_colvar.data VALUES=phi1
rphi2:
READ FILE=input_colvar.data VALUES=phi2
PRINT ARG=rphi1,rphi2 STRIDE=500 FILE=output_colvar.data
Generated by Doxygen
628
9.5
Command Line Tools
gentemplate
This is part of the cltools module
gentemplate is a tool that you can use to construct template inputs for the various actions
The templates generated by this tool are primarily for use with Toni Giorgino's VMD GUI. It may be useful however
to use this tool as a quick aid memoir.
Options
--help/-h
--list
--include-optional
( default=off ) print this help
--action
print the template for this particular action
( default=off ) print a list of the available actions
( default=off ) also print optional modifiers
Examples
The following generates template input for the action DISTANCE.
plumed gentemplate --action DISTANCE
9.6
info
This is part of the cltools module
This tool allows you to obtain information about your plumed version
You can specify the information you require using the following command line arguments
Options
--help/-h
--configuration
--root
--user-doc
--developer-doc
--version
--long-version
--git-version
--include-dir
--soext
( default=off ) print this help
( default=off ) prints the configuration file
( default=off ) print the location of the root directory for the plumed source
( default=off ) print the location of user manual (html)
( default=off ) print the location of user manual (html)
( default=off ) print the version number
( default=off ) print the version number (long version)
( default=off ) print the version number (git version, if available)
( default=off ) print the location of the include dir
( default=off ) print the extension of shared libraries (so or dylib)Generated by Doxygen
9.8 manual
629
Examples
The following command returns the root directory for your plumed distribution.
plumed info --root
9.7
kt
This is part of the cltools module
Print out the value of kB T at a particular temperature
Compulsory keywords
--temp
--units
print the manual for this particular action
( default=kj/mol ) the units of energy can be kj/mol, kcal/mol, j/mol, eV or the conversion factor from
kj/mol
Options
--help/-h
( default=off ) print this help
Examples
The following command will tell you the value of kB T when T is equal to 300 K in eV
plumed kt --temp 300 --units eV
9.8
manual
This is part of the cltools module
manual is a tool that you can use to construct the manual page for a particular action
The manual constructed by this action is in html. In all probability you will never need to use this tool. However, it is
used within the scripts that generate the html manual for PLUMED. If you need to use this tool outside those scripts
the input is specified using the following command line arguments.
Generated by Doxygen
630
Command Line Tools
Compulsory keywords
--action
print the manual for this particular action
Options
--help/-h
--vim
--spelling
( default=off ) print this help
( default=off ) print the keywords in vim syntax
( default=off ) print a list of the keywords and component names for the spell checker
Examples
The following generates the html manual for the action DISTANCE.
plumed manual --action DISTANCE
9.9
mklib
compile a .cpp file into a shared library
Note
This command line tool is implemented as a shell script. Its help message is pasted below:
ERROR
type ’plumed mklib file.cpp’
9.10
newcv
create a new collective variable from a template
Note
This command line tool is implemented as a shell script. Its help message is pasted below:
ERROR
type ’plumed newcv directive classname’
E.g. ’plumed newcv TORSION Torsion’
Generated by Doxygen
9.11 partial_tempering
9.11
631
partial_tempering
create a new collective variable from a template
Note
This command line tool is implemented as a shell script. Its help message is pasted below:
Usage:
plumed partial_tempering [--gromacs4] scale < processed.top
where scale is the Hamiltonian scaling factor and
processed.top is a post-processed topology file (i.e. produced with grompp -pp)
where each "hot" atom has a "_" appended to the atom type, e.g.:
1 amber99_43_
1
RC5
O5’
1
-0.6223
16
; qtot -0.6223
Notice that the section that should be edited is the [atoms] section for all the
molecules that you wish to affect (typically only for the solute, but you may also
want to change solvent parameters).
Also remember to first produce the processed.top file with grompp -pp. Editing a normal
topol.top file will not work, because it does not contain all the parameters.
The processed.top file should not have any "#include" statement.
# produce a processed topology
grompp -pp
# choose the "hot" atoms
vi processed.top
# generate the actual topology
plumed partial_tempering $scale < processed.top > topol$i.top
WARNING: It’s not very robust and there might be force-field dependent issues!
A few tests are strongly suggested.
1. Compare partial_tempering with scale=1.0 to non-scaled force field. E.g.
grompp -o topol-unscaled.tpr
grompp -pp
vi processed.top # choose the "hot" atoms appending "_". You can choose whatever.
plumed partial_tempering 1.0 < processed.top > topol-scaled.top # scale with factor 1
grompp -p topol-scaled.top -o topol-scaled.tpr
# Then do a rerun on a trajectory
mdrun -s topol-unscaled.tpr -rerun rerun.trr
mdrun -s topol-scaled.tpr -rerun rerun.trr
# and compare the resuling energy files. they should be identical
2. Compare partial_tempering with scale=0.5 to non-scaled force field.
Repeat the same procedure but using "plumed partial_tempering 0.5".
Choose all the atoms in all the relevant [atoms] sections (e.g. solute, solvent and ions).
In the two resulting energy files you should see:
long range electrostatics, LJ, and dihedral energy is *half* in the scaled case
all other terms (bonds/bends) are identical.
9.12
patch
patch an MD engine
Generated by Doxygen
632
Command Line Tools
Note
This command line tool is implemented as a shell script. Its help message is pasted below:
Actions (choose one):
-h, --help
print this help and exit
-p, --patch
patch
-r, -R, --revert
revert
-l, --list-engines
print a list of available MD engines
-s, --save
save, this needs *.preplumed files (*)
--save-originals
same as save, but save also original files (*)
-n NEWENGINE, --new NEWENGINE
create a new patch named NEWENGINE (*)
-i, --info
output information on the patching procedure for a particular code
Options:
-e ENGINE, --engine ENGINE
set MD engine to ENGINE (default: choose interactively)
-m MODE, --mode MODE (default: shared)
set link mode to MODE, which can be either static, shared or runtime
--static
same as --mode static
--shared
same as --mode shared
--runtime
same as --mode runtime
-d FILE, --diff FILE
set the path to diff file (default: ROOT/patches/ENGINE.diff) (*)
-q, --quiet
do not write loggin information; useful with -i to print just
the patching information
-f, --force
force patching (*)
(*) These options are for developers or for testing only. Be sure to know what
you are doing before you use them.
9.13
pathtools
This is part of the mapping module
pathtools can be used to construct paths from pdb data
The path CVs in PLUMED are curvilinear coordinates through a high dimensional vector space. Enhanced sampling
calculations are often run using the progress along the paths and the distance from the path as CVs as this provides
a convenient way of defining a reaction coordinate for a complicated process. This method is explained in the
documentation for PATH.
The path itself is an ordered set of equally-spaced, high-dimensional frames the way in which these frames should
be constructed will depend on the problem in hand. In other words, you will need to understand the reaction you
wish to study in order to select a sensible set of frames to use in your path CV. This tool provides two methods that
may be useful when it comes to constructing paths; namely:
• A tool that takes in an initial guess path in which the frames are not equally spaced. This tool adjusts the
positions of the frames in order to make them equally spaced so that they can be used as the basis for a path
CV.
Generated by Doxygen
9.13 pathtools
633
• A tool that takes two frames as input and that allows you to return a linear path connecting these two frames.
The output from this method may be useful as an initial guess path. It is arguable that a linear path rather
defeats the purpose of the path CV method, however, as the whole purpose is to be able to define non-linear
paths.
Notice that you can use these two methods and take advantage of all the ways of measuring Distances from reference configurations
that are available within PLUMED. The way you do this with each of these tools described above is explained in the
example below.
The atoms involved can be specified using
--start
a pdb file that contains the structure for the initial frame of your path. For more information on how
to specify lists of atoms see Groups and Virtual Atoms
--end
a pdb file that contains the structure for the final frame of your path. For more information on how
to specify lists of atoms see Groups and Virtual Atoms
Or alternatively by using
--path
a pdb file that contains an initial path in which the frames are not equally spaced
Compulsory keywords
--fixed
--metric
--out
--arg-fmt
--tolerance
( default=0 ) the frames to fix when constructing the path using –path
--nframes-before-start
( default=1 ) the number of frames to include in the path before the first
frame
( default=1 ) the number of frames between the start and end frames in your
path
--nframes
--nframes-after-end
the measure to use to calculate the distance between frames
the name of the file on which to output your path
( default=f ) the format to use for argument values in your frames
( default=1E-4 ) the tolerance to use for the algorithm that is used to reparameterize the path
( default=1 ) the number of frames to put after the last frame of your path
Options
--help/-h
( default=off ) print this help
Examples
The example below shows how you can take a set of unequally spaced frames from a pdb file named in_path.←Generated by Doxygen
634
Command Line Tools
pdb and use pathtools to make them equally spaced so that they can be used as the basis for a path CV. The file
containing this final path is named final_path.pdb.
plumed pathtools --path in_path.pdb --metric EUCLIDEAN --out final_path.pdb
The example below shows how can create an initial linear path connecting the two pdb frames in start.pdb and
end.pdb. In this case the path output to path.pdb will consist of 6 frames: the initial and final frames that were
contained in start.pdb and end.pdb as well as four equally spaced frames along the vector connecting start.pdb to
end.pdb.
plumed pathtools --start start.pdb --end end.pdb --nframes 4 --metric OPTIMAL --out path.pdb
Often the idea with path collective variables is to create a path connecting some initial state A to some final state
B. You would in this case have representative configurations from your A and B states defined in the input files to
pathtools that we have called start.pdb and end.pdb in the example above. Furthermore, it may be useful to have a
few frames before your start frame and after your end frame. You can use path tools to create these extended paths
as shown below. In this case the final path would now consist of 8 frames. Four of these frames would lie on the
vector connecting state A to state B, there would be one frame each at start.pdb and end.pdb as well as one frame
just before start.pdb and one frame just after end.pdb. All these frames would be equally spaced.
plumed pathtools --start start.pdb --end end.pdb --nframes 4 --metric OPTIMAL --out path.pdb --nframes-before-
Notice also that when you re-parameterize paths you must choose two frames to fix. Generally you chose to fix the
states that are representative of your states A and B. By default pathtools will fix the first and last frames. You can,
however, change the states to fix by taking advantage of the fixed flag as shown below.
plumed pathtools --path inpath.pdb --metric EUCLIDEAN --out outpath.pdb --fixed 2,12
9.14
pdbrenumber
This is part of the cltools module
Modify atom numbers in a PDB, possibly using hybrid-36 coding.
When reading a PDB files, PLUMED honors the serial number of each atom. This command can be used to
process a PDB file changing the atom serial numbers. Notice that the resulting list might have gaps. It is however
fundamental that atom numbers correspond to those used within the MD code. Importantly, if the serial number of
an atom is greater than 99999, it is written in hybrid-36 notation (see pdbreader). The main use of pdbrenumber is
thus that of producing files where atoms are numbered using hybrid-36 convention.
The output PDB file is identical to the input PDB file, except for the atom number field. The rest of the line is written
unchanged to the output file, even if it is incorrectly formatted. Residue numbers are not touched, and atom numbers
in the input file are ignored.
Compulsory keywords
Generated by Doxygen
9.15 pesmd
635
--ipdb
--opdb
specify the name of the input PDB file
specify the name of the output PDB file
Options
--help/-h
( default=off ) print this help
--firstatomnumber
--atomnumbers
specify the desired serial number of the first atom of the output file
specify the desired serial numbers of the atoms of the output file using a separate list
Examples
By default, pdbreader just sets the numbers as progressive starting from 1. For instance the following command:
> plumed pdbrenumber --ipdb input.pdb --opdb output.pdb
will copy file input.pdb to output.pdb replacing all the serial atoms with increasing numbers starting from
one. Atoms that have an index that is greater than 99999 will be written in the output PDB file in hybrid-36 code.
It is possible to set a different serial number for the first atom, letting the following ones grow by one at each line.
Here for instance the first atom will be assigned serial 1000, the second serial 1001, etc:
> plumed pdbrenumber --ipdb input.pdb --opdb output.pdb --firstatomnumber 1000
If the first atom number is >99999, it should be given as a decimal number (not in hybrid-36 code). However,
numbers >99999 in the output PDB file will be written in hybrid-36 code.
As an alternative, one can provide a list of atoms as one per line in an auxiliary file.
> plumed pdbrenumber --ipdb input.pdb --opdb output.pdb --atomnumbers list.txt
The list.txt file might be something like this
120000
120001
120002
1
2
3
Numbers >99999 in the list should be provided as decimal numbers (not in hybrid-36 code). However, numbers
>99999 in the output PDB file will be written in hybrid-36 code. Notice that there should be at least enough lines in
list.txt as many atoms in the PDB file. Additional lines in list.txt will just be ignored.
9.15
pesmd
Generated by Doxygen
636
Command Line Tools
This is part of the cltools module
Pesmd allows one to do (biased) Langevin dynamics on a two-dimensional potential energy surface.
The energy landscape that you are moving about on is specified using a plumed input file. The directives that are
available for this command line tool are as follows:
Compulsory keywords
nstep
The number of steps of dynamics you want to run
temperature
( default=NVE ) the temperature at which you wish to run the simulation in LJ units
friction
( default=off ) The friction (in LJ units) for the Langevin thermostat that is used to keep the
temperature constant
tstep
( default=0.005 ) the integration timestep in LJ units
dimension
the dimension of your energy landscape
plumed
( default=plumed.dat ) the name of the plumed input file containing the potential
ipos
( default=0.0 ) the initial position of the system
idum
( default=0 ) The random number seed
Options
periodic
( default=on ) are your input coordinates periodic
min
minimum value the coordinates can take for a periodic domain
max
maximum value the coordinates can take for a periodic domain
Examples
You run a Langevin simulation using pesmd with the following command:
plumed pesmd < input
The following is an example of an input file for a pesmd simulation. This file instructs pesmd to do 50 steps of
Langevin dynamics on a 2D potential energy surface at a temperature of 0.722
temperature 0.722
tstep 0.005
friction 1
dimension 2
nstep 50
ipos 0.0 0.0
If you run the following a description of all the directives that can be used in the input file will be output.
plumed pesmd --help
Generated by Doxygen
9.16 simplemd
637
The energy landscape to explore is given within the plumed input file. For example the following example input uses
MATHEVAL to define a two dimensional potential.
d1: DISTANCE ATOMS=1,2 COMPONENTS
ff: MATHEVAL ARG=d1.x,d1,y PERIODIC=NO FUNC=()
bb: BIASVALUE ARG=ff
Atom 1 is placed at the origin. The x and y components on our surface are the positions of the particle on our two
dimensional energy landscape. By calculating the vector connecting atom 1 (the origin) to atom 2 (the position of
our particle) we are thus getting the position of the atom on the energy landscape. This is then inserted into the
function that is calculated on the second line. The value of this function is then used as a bias.
We can also specify a potential on a grid and look at the dynamics on this function using pesmd. A plumed input for
an example such as this one might look something like this:
d1: DISTANCE ATOMS=1,2 COMPONENTS
bb: EXTERNAL ARG=d1.x,d1,y FILE=fes.dat
In this way we can use pesmd to do a dynamics on a free energy surface calculated using metadynamics and
sum_hills. On a final note once we have defined our potential we can use all the biasing functions within plumed in
addition in order to do a biased dynamics on the potential energy landscape of interest.
9.16
simplemd
This is part of the cltools module
simplemd allows one to do molecular dynamics on systems of Lennard-Jones atoms.
The input to simplemd is specified in an input file. Configurations are input and output in xyz format. The input file
should contain one directive per line. The directives available are as follows:
Compulsory keywords
nstep
The number of steps of dynamics you want to run
temperature
( default=NVE ) the temperature at which you wish to run the simulation in LJ units
friction
( default=off ) The friction (in LJ units) for the Langevin thermostat that is used to keep the
temperature constant
tstep
( default=0.005 ) the integration timestep in LJ units
inputfile
An xyz file containing the initial configuration of the system
forcecutoff
( default=2.5 )
listcutoff
( default=3.0 )
outputfile
An output xyz file containing the final configuration of the system
nconfig
( default=10 ) The frequency with which to write configurations to the trajectory file followed
by the name of the trajectory file
nstat
( default=1 ) The frequency with which to write the statistics to the statistics file followed by
the name of the statistics file
( default=10000 ) The maximum number of neighbors an atom can have
maxneighbours
Generated by Doxygen
638
Command Line Tools
idum
( default=0 ) The random number seed
ndim
( default=3 ) The dimensionality of the system (some interesting LJ clusters are two dimensional)
wrapatoms
( default=false ) If true, atomic coordinates are written wrapped in minimal cell
Examples
You run an MD simulation using simplemd with the following command:
plumed simplemd < in
The following is an example of an input file for a simplemd calculation. This file instructs simplemd to do 50 steps of
MD at a temperature of 0.722
nputfile input.xyz
outputfile output.xyz
temperature 0.722
tstep 0.005
friction 1
forcecutoff 2.5
listcutoff 3.0
nstep 50
nconfig 10 trajectory.xyz
nstat
10 energies.dat
If you run the following a description of all the directives that can be used in the input file will be output.
plumed simplemd --help
9.17
sum_hills
This is part of the cltools module
sum_hills is a tool that allows one to to use plumed to post-process an existing hills/colvar file
Options
--help/-h
--help-debug
--negbias
( default=off ) print this help
--nohistory
( default=off ) to be used with –stride: it splits the bias/histogram in pieces without previous
history
--mintozero
( default=off ) it translate all the minimum value in bias/histogram to zero (useful to compare
results)
--hills
specify the name of the hills file
( default=off ) print special options that can be used to create regtests
( default=off ) print the negative bias instead of the free energy (only needed with well
tempered runs and flexible hills)
Generated by Doxygen
9.17 sum_hills
639
--histo
--stride
--min
--max
--bin
--spacing
--idw
specify the name of the file for histogram a colvar/hills file is good
--outfile
--outhisto
--kt
--sigma
--fmt
specify the output file for sumhills
specify the stride for integrating hills file (default 0=never)
the lower bounds for the grid
the upper bounds for the grid
the number of bins for the grid
grid spacing, alternative to the number of bins
specify the variables to be used for the free-energy/histogram (default is all). With –hills the
other variables will be integrated out, with –histo the other variables won't be considered
specify the output file for the histogram
specify temperature in energy units for integrating out variables
a vector that specify the sigma for binning (only needed when doing histogram
specify the output format
Examples
a typical case is about the integration of a hills file:
plumed sum_hills
--hills PATHTOMYHILLSFILE
The default name for the output file will be fes.dat Note that starting from this version plumed will automatically
detect the number of the variables you have and their periodicity. Additionally, if you use flexible hills (multivariate
Gaussian kernels), plumed will understand it from the HILLS file.
The sum_hills tool will also accept multiple files that will be integrated one after the other
plumed sum_hills
--hills PATHTOMYHILLSFILE1,PATHTOMYHILLSFILE2,PATHTOMYHILLSFILE3
if you want to integrate out some variable you do
plumed sum_hills
--hills PATHTOMYHILLSFILE
--idw t1 --kt 0.6
where with –idw you define the variables that you want all the others will be integrated out. –kt defines the temperature of the system in energy units. (be consistent with the units you have in your hills: plumed will not check this
for you) If you need more variables then you may use a comma separated syntax
plumed sum_hills
--hills PATHTOMYHILLSFILE
--idw t1,t2 --kt 0.6
You can define the output grid only with the number of bins you want while min/max will be detected for you
plumed sum_hills --bin 99,99 --hills PATHTOMYHILLSFILE
or full grid specification
plumed sum_hills --bin 99,99 --min -pi,-pi --max pi,pi --hills PATHTOMYHILLSFILE
Generated by Doxygen
640
Command Line Tools
You can of course use numbers instead of -pi/pi.
You can use a –stride keyword to have a dump each bunch of hills you read
plumed sum_hills --stride 300 --hills PATHTOMYHILLSFILE
You can also have, in case of well tempered metadynamics, only the negative bias instead of the free energy through
the keyword –negbias
plumed sum_hills --negbias --hills PATHTOMYHILLSFILE
Here the default name will be negativebias.dat
From time to time you might need to use HILLS or a COLVAR file as it was just a simple set of points from which
you want to build a free energy by using -(1/beta)log(P) then you use –histo
plumed sum_hills --histo PATHTOMYCOLVARORHILLSFILE
--sigma 0.2,0.2 --kt 0.6
in this case you need a –kt to do the reweighting and then you need also some width (with the –sigma keyword) for
the histogram calculation (actually will be done with Gaussian kernels, so it will be a continuous histogram) Here
the default output will be histo.dat. Note that also here you can have multiple input files separated by a comma.
Additionally, if you want to do histogram and hills from the same file you can do as this
plumed sum_hills --hills --histo PATHTOMYCOLVARORHILLSFILE
--sigma 0.2,0.2 --kt 0.6
The two files can be eventually the same
Another interesting thing one can do is monitor the difference in blocks as a metadynamics goes on. When the bias
deposited is constant over the whole domain one can consider to be at convergence. This can be done with the
–nohistory keyword
plumed sum_hills --stride 300 --hills PATHTOMYHILLSFILE
--nohistory
and similarly one can do the same for an histogram file
plumed sum_hills --histo PATHTOMYCOLVARORHILLSFILE
--sigma 0.2,0.2 --kt 0.6 --nohistory
just to check the hypothetical free energy calculated in single blocks of time during a simulation and not in a cumulative way
Output format can be controlled via the –fmt field
plumed sum_hills --hills PATHTOMYHILLSFILE
--fmt %8.3f
where here we chose a float with length of 8 and 3 digits
The output can be named in a arbitrary way :
plumed sum_hills --hills PATHTOMYHILLSFILE
--outfile myfes.dat
will produce a file myfes.dat which contains the free energy.
If you use stride, this keyword is the suffix
plumed sum_hills --hills PATHTOMYHILLSFILE
--outfile myfes_ --stride 100
will produce myfes_0.dat, myfes_1.dat, myfes_2.dat etc.
The same is true for the output coming from histogram
plumed sum_hills --histo HILLS --kt 2.5 --sigma 0.01 --outhisto myhisto.dat
is producing a file myhisto.dat while, when using stride, this is the suffix
plumed sum_hills --histo HILLS --kt 2.5 --sigma 0.01 --outhisto myhisto_ --stride 100
that gives myhisto_0.dat, myhisto_1.dat, myhisto_3.dat etc..
Generated by Doxygen
9.18 vim2html
9.18
641
vim2html
convert plumed input file to colored html using vim syntax
Note
This command line tool is implemented as a shell script. Its help message is pasted below:
Usage:
plumed vim2html [options] < input > output
plumed vim2html [options] input > output
plumed vim2html [options] input output
(one of the three)
Options can be:
--annotate-syntax Reports annotated syntax on output.
Also reports non-annotated regions on stderr
--pdf
To produce a pdf file with syntax highlighting.
--crop
Crop the pdf file to the only written part. Usefull to insert the pdf in a LaTex file as ima
--fs
Specify the fontsize of the pdf output.
--colors
Specify the color palette. Allowed values are: default/ac
Generated by Doxygen
642
Command Line Tools
Generated by Doxygen
Chapter 10
Miscelaneous
• Comments
• Continuation lines
• Using VIM syntax file
• Using bash autocompletion
• Including other files
• Loading shared libraries
• Embed a separate PLUMED instance
• Debugging the code
• Changing exchange patterns in replica exchange
• List of modules
• Special replica syntax
• Parsing constants
• Frequently used tools
10.1
Comments
If you are an organized sort of person who likes to remember what the hell you were trying to do when you ran
a particular simulation you might find it useful to put comments in your input file. In PLUMED you can do this as
comments can be added using a # sign. On any given line everything after the # sign is ignored so erm... yes add
lines of comments or trailing comments to your hearts content as shown below (using Shakespeare is optional):
BEGIN_PLUMED_FILE
# This is the distance between two atoms:
DISTANCE ATOM=1,2 LABEL=d1
UPPER_WALLS ARG=d1 AT=3.0 KAPPA=3.0 LABEL=Snout # In this same interlude it doth befall.
# That I, one Snout by name, present a wall.
(see DISTANCE and UPPER_WALLS)
An alternative to including comments in this way is to use the command ENDPLUMED. Everything in the PLUMED
input after this keyword will be ignored.
644
10.1.1
Miscelaneous
ENDPLUMED
Terminate plumed input.
Can be used to effectively comment out the rest of the input file. It can be useful to quickly ignore part of a long input
file. However, one should keep in mind that when opening the file it might be difficult to find where the commented
out part begins. Regular comments (with #) are usually easier to read. Notice that VIM syntax should be able to
detect this command and properly mark the rest of the file as a comment, although since vim doesn't parse the
whole file it might fail in doing so for long input files.
Examples
BEGIN_PLUMED_FILE
d: DISTANCE ATOMS=1,10
PRINT ARG=d FILE=COLVAR STRIDE=10
ENDPLUMED
commands here are ignored
PRINT ARG=d FILE=COLVAR STRIDE=1
10.2
Continuation lines
If your input lines get very long then editing them using vi and other such text editors becomes a massive pain in
the arse.
We at PLUMED are aware of this fact and thus have provided a way of doing line continuations so as to make
your life that much easier - aren't we kind? Well no not really, we have to use this code too. Anyway, you can do
continuations by using the "..." syntax as this makes this:
BEGIN_PLUMED_FILE
DISTANCES ATOMS1=1,300 ATOMS2=1,400 ATOMS3=1,500 LABEL=dist
(see DISTANCES)
equivalent to this:
BEGIN_PLUMED_FILE
DISTANCES ...
LABEL=dist
# we can also insert comments here
ATOMS1=1,300
# multiple kewords per line are allowed
ATOMS2=1,400 ATOMS3=1,500
#empty lines are also allowed
... DISTANCES
Notice that the closing ... is followed by the word DISTANCES. This is optional, but might be useful to find more
easily which is the matching start of the statement. The following is equally correct
BEGIN_PLUMED_FILE
DISTANCES ...
LABEL=dist
# we can also insert comments here
ATOMS1=1,300
# multiple kewords per line are allowed
ATOMS2=1,400 ATOMS3=1,500
#empty lines are also allowed
...
Generated by Doxygen
10.3 Using VIM syntax file
645
Notice that PLUMED makes a check that the word following the closing ... is actually identical to the first word in
the line with the first .... If not, it will throw an error. Also notice that you might put more than one word in the first
line. E.g.
BEGIN_PLUMED_FILE
DISTANCES LABEL=dist ...
# we can also insert comments here
ATOMS1=1,300
# multiple kewords per line are allowed
ATOMS2=1,400 ATOMS3=1,500
#empty lines are also allowed
...
or, equivalently,
BEGIN_PLUMED_FILE
dist: DISTANCES ...
# we can also insert comments here
ATOMS1=1,300
# multiple kewords per line are allowed
ATOMS2=1,400 ATOMS3=1,500
#empty lines are also allowed
...
10.3
Using VIM syntax file
For the impatient use:
• Add the following to your .vimrc file:
" Enable syntax
:syntax on
" This allows including the proper PLUMED syntax file:
:let &runtimepath.=’,’.$PLUMED_VIMPATH
" The former command requires PLUMED_VIMPATH to be set. Alternatively, use this:
" let &runtimepath.=’,/usr/local/lib/plumed/vim’
" properly adjusted to the path where PLUMED is installed.
" This makes autocompletion work in the expected way:
:set completeopt=longest,menuone
" This enables bindings of F2/F3/F4 to plumed specific commands:
:let plumed_shortcuts=1
• When you open a PLUMED input file, you can enable syntax highlighting with:
:set ft=plumed
This will also enable autocompletion. Use to autocomplete a word.
• If you want to fold multi-line statements, type
:setlocal foldmethod=syntax
• While editing a plumed input file, you can use command :PHelp (or shortcut ) to show in a split
window a short help about the action defined in the line where the cursor is. Typing :PHelp again (or
pushing ) you will close that window. With you go back and forth between
the two windows.
• When you open a file starting with #! FIELDS, VIM will automatically understand it is a PLUMED output
file (VIM filetype = plumedf) and will color fields and data columns with alternating colors. Typing :PPlus
and :PMinus (or pushing and ) you can move a highlighted column.
Generated by Doxygen
646
Miscelaneous
See below for more detailed instructions.
Configuration
When PLUMED is compiled, directories help and syntax will appear in builddir/vim. They contain a VIM
plugin that can be used to highlight proper PLUMED instructions in a PLUMED input file and to quickly retrieve help.
There is also a file builddir/vim/scripts.vim that helps VIM in recognizing PLUMED output files.
Warning
Notice that these file do not appear if you are cross compiling. In this case, you must copy the plugin files from
another machine.
To make VIM aware of these files, you should copy them to your $HOME/.vim directory. Later you can enable
plumed syntax with the command
:set ft=plumed
If you work in an environment where several PLUMED versions are installed (e.g. using env modules), we recommend the following procedure:
• Install PLUMED
• Add to your .vimrc file the following line:
:let &runtimepath.=’,’.$PLUMED_VIMPATH
The modulefile provided with PLUMED should set the PLUMED_VIMPATH environment variable to the proper path.
Thus, when working with a given PLUMED module loaded, you should be able to enable to proper syntax by just
typing
:set ft=plumed
in VIM. Notice that the variable PLUMED_VIMPATH is also set in the sourceme.sh script in the build directory.
Thus, if you modify your .vimrc file as suggested, you will be able to use the correct syntax both when using
an installed PLUMED and when running from a just compiled copy. Finally, in case you have both a preinstalled
PLUMED and you have your development version the following command would give you the optimal flexibility:
:let &runtimepath.=’,’.$PLUMED_VIMPATH.’,/opt/local/lib/plumed/vim/’
The environment variable PLUMED_VIMPATH, if set, will take the precedence. Otherwise, vim will resort to the
hard coded path. In this case we assumed that there is a PLUMED installed in /opt/local/ (e.g. using Mac←Ports), but you can override it sourcing a sourceme.sh file in the compilation directory or loading a PLUMED
module with module load plumed.
If you are tired of typing :set ft=plumed, you can use a modeline. Add to your .vimrc file the following
commands
:set modeline
:set modelines=5
Then, at the beginning of your PLUMED input file, put the following comment:
Generated by Doxygen
10.3 Using VIM syntax file
647
BEGIN_PLUMED_FILE
# vim:ft=plumed
d: DISTANCE ATOMS=1,2
RESTRAINT ARG=d AT=0.0 KAPPA=1.0
Now, every time you open this file, you will see it highlighted.
Syntax highlighting
The syntax file contains a definition of all possible PLUMED actions and keywords. It is designed to allow for a
quick validation of the PLUMED input file before running it. As such, all the meaningful words in the input should be
highlighted:
• Valid action names (such as METAD) and labels (such as m: or LABEL=m) will be highlighted in the brightest
way (Type in VIM). Those are the most important words.
• Keyword and flag names (such as ATOMS= or COMPONENTS when part of the action DISTANCE) will be
highlighted with a different color (Statement in VIM).
• Values provided by users (such as the number of the atoms following ATOMS=) will be highlighted with a
different color (String in VIM).
• Comments (see Comments) will be highlighted as comments (Comment in VIM).
• String __FILL__ (extensively used in tutorials to indicate parts to be completed) is highlighted (Todo in
VIM).
If you see something that is not highlighted and appears in black, this is likely going to result in an error at runtime.
Think of this as a sort of preliminary spell-check. For this checks to be effective, we recommend to use a syntax file
generated with exactly the same version of PLUMED that you are using. In case you find that parts of an input file
that is valid are not highlighted, then please report it as a bug. On the contrary, you cannot expect the VIM syntax
file to recognize all possible errors in a PLUMED input. Thus, a file for which the highlighting looks correct might still
contain errors.
Multi-line folding
Notice that syntax highlighting also allow VIM to properly fold multi-line actions. Try to do the following:
• Open a PLUMED input file
• Enable PLUMED syntax
:set ft=plumed
• Enable syntax-based folding
:setlocal foldmethod=syntax
Now look at what happened to all the multi-line statements in PLUMED (i.e. those using Continuation lines). As you
can see, they will be folded into single lines. Folded lines can be expanded with zo and folded with zc. Look at
VIM documentation to learn more. In case you want to use this feature, we suggest you to put both label and action
type on the first line of multi-line statements. E.g.
Generated by Doxygen
648
Miscelaneous
BEGIN_PLUMED_FILE
m: METAD ...
ARG=d
HEIGHT=1.0
SIGMA=0.5
PACE=100
...
will be folded to
+--
6 lines: m: METAD ...------------------------------------------------------
and
BEGIN_PLUMED_FILE
METAD LABEL=m ...
ARG=d
HEIGHT=1.0
SIGMA=0.5
PACE=100
...
will be folded to
+--
6 lines: METAD LABEL=m ...-------------------------------------------------
This will allow you to easily identify the folded lines by seeing the most important information, that is the action type
(METAD) and its label (m). This feature is convenient if you want to browse files that contain a lot of actions defined
on multiple lines.
Autocompletion
Another VIM feature that comes when you load PLUMED syntax is autocompletion of PLUMED actions and keywords. Open your favorite PLUMED input file and set it to PLUMED syntax highlighting with
:set ft=plumed
Now go into insert mode pressing i and type DU followed by . Here stands
for autocompletion and for omnifunc autocompletion. You will see a short menu listing the following
actions
DUMPATOMS
DUMPDERIVATIVES
DUMPFORCES
DUMPMASSCHARGE
DUMPMULTICOLVAR
DUMPPROJECTIONS
That is, all the actions starting with DU. You can navigate it with up and down arrows so as to choose the best match.
Notice that the default behavior of VIM is to use the first match by default. In the first example (DU, as usually in vim. Notice that if you
are in the help window and type :PHelp this window will be closed.
To make the navigation easier, you can add a shortcut in your .vimrc file. For example, adding:
: nmap : PHelp
you should be able to open and close the manual hitting the F2 key. This is done automatically in the PLUMED
syntax file if you add let plumed_shortcuts=1 to your vimrc file.
Displaying output files
Most of the PLUMED output files look like this
#! FIELDS A B C
1 2 3
This is useful since in the header you can see the name of the quantities that are printed in the data lines. However,
when you have an output file with many columns it might be a bit error prone to count them. To simplify this, when
PLUMED syntax for VIM is configured properly VIM should be able to:
• Detect that this file is a PLUMED output file with fields, automatically setting its type to plumedf. If not, just
type :set ft=plumedf.
Generated by Doxygen
650
Miscelaneous
• Show this file with syntax highlighting to increase its readability.
Notice that the syntax file for the output files (plumedf.vim) is not the same one that is used for the PLUMED
input file (plumed.vim).
To make output files more readable, vim will show FIELDS and SET words in a different color, and data columns
with alternating colors (e.g. dark/light/dark/light). The colors in the columns are consistent with those shown in the
FIELD line. In the example above, 1, 2, and 3 will be of the same color as A, B, and C respectively. This should
make it much easier to find which columns correspond to a given quantity.
It is also possible to highlight a specific field of the file. Typing
:5PCol
you will highlight the fifth field. Notice that in the FIELDS line (the first line of the file) the seventh word of the
line will be highlighted, which is the one containing the name of the field. This allows for easy matching of values
shown in the file and tags provided in the FIELDS line. The highlighted column can be moved back and forth using
:PPlus and :PMinus. Adding a count to the command will move the highlighted column more. E.g. :2PPlus
will move the column to the right twice.
If you have a long output file, it might be convenient to split it with :split so that one of the two windows will only
show the header. The other window can be used to navigate the file.
To make the navigation easier, you can add a shortcut in your .vimrc file. For example, adding:
: map :PMinus
: map :PPlus
you should be able to move the highlight column using F3 and F4 buttons. This is done automatically in the PLUMED
syntax file if you add let plumed_shortcuts=1 to your vimrc file.
10.4
Using bash autocompletion
When possible, PLUMED tries to install bash autocompletion so that you do not have to do anything. Just use the
key to complete plumed commands (e.g. plumed dr) or even options (e.g. plumed driver
--i). In case this does not work, you might have to add the following lines to your .bashrc file:
_plumed() { eval "$(plumed --no-mpi completion 2>/dev/null)";}
complete -F _plumed -o default plumed
Effect
When typing on the the shell you should observe the following behavior.
> plumed
will autocomplete with the names of the available PLUMED commands (e.g. driver, help, etc).
> plumed -
Generated by Doxygen
10.4 Using bash autocompletion
651
will autocomplete with the available PLUMED options (e.g. --no-mpi, etc).
PLUMED also knows which are the options available for each command (e.g. plumed driver --natoms).
So, the following
> plumed driver -
(notice the -) will autocomplete to the options of plumed driver. On the contrary
> plumed driver --ixtc
(notice the there is no - before ) will autocomplete to the files in the current directory.
Also notice that every time you use the key to autocomplete the command plumed will be invoked. This
should allow the correct commands and options to be reported depending on the exact plumed command in the
current execution path. For instance, if you have multiple PLUMED versions installed with env modules, you should
be able to see the commands available in the currently loaded version. Clearly, this feature will only be available if
plumed can run on this machine (that is: will not work if you are cross compiling). This is not a problem since you
are not expecting to run the plumed command in this specific case.
Technicalities
At configure time if the variable BASH_COMPLETION_DIR is defined it will be used to decide where PLUMED
autocompletion should be installed. Otherwise, configure will look for the presence of the bash-completion
package and, in case it is installed on the same prefix as PLUMED, also PLUMED autocompletion will be installed.
Finally, if none of these two conditions are satisfied, autocompletion will not be enabled. You will have to change
your bashrc file once adding the following lines:
_plumed() { eval "$(plumed --no-mpi completion 2>/dev/null)";}
complete -F _plumed -o default plumed
The command plumed completion just writes on its standard output the body of a bash function that is then
used by bash to construct the autocompletion. The --no-mpi flag makes it more likely that the command can be
executed correctly e.g. when you are on the login node of a cluster and PLUMED was compiled with MPI but the
login node does not support MPI. In other cases, it is harmless. The -o default options will make sure that if
plumed --no-mpi completion returns an error the default bash completion will be used. This is what will
happen if you load an older PLUMED version for which the completion command is not available yet. In future
PLUMED versions the plumed completion command might return more sophisticated functions. You should
be able to benefit of these features without ever changing your bash configuration file again.
Multiple versions and suffixes
In case you have multiple versions of PLUMED installed in separate env modules there is nothing more to do.
However, if you have have multiple versions of PLUMED installed with different suffixes you should consistently add
more lines to your profile file. For instance, if you installed two executables named plumed and plumed_mpi
your configuration file should look like:
_plumed() { eval "$(plumed --no-mpi completion 2>/dev/null)";}
complete -F _plumed -o default plumed
_plumed_mpi() { eval "$(plumed_mpi --no-mpi completion 2>/dev/null)";}
complete -F _plumed_mpi -o default plumed_mpi
Generated by Doxygen
652
10.5
Miscelaneous
Including other files
If, for some reason, you want to spread your PLUMED input over a number of files you can use INCLUDE as shown
below:
BEGIN_PLUMED_FILE
INCLUDE FILE=filename
So, for example, a single "plumed.dat" file:
BEGIN_PLUMED_FILE
DISTANCE ATOMS=0,1 LABEL=dist
RESTRAINT ARG=dist
could be split up into two files as shown below:
BEGIN_PLUMED_FILE
DISTANCE ATOMS=0,1 LABEL=dist
INCLUDE FILE=toBeIncluded.dat
plus a "toBeIncluded.dat" file
BEGIN_PLUMED_FILE
RESTRAINT ARG=dist
However, when you do this it is important to recognize that INCLUDE is a real directive that is only resolved after all
the Comments have been stripped and the Continuation lines have been unrolled. This means it is not possible to
do things like:
BEGIN_PLUMED_FILE
# this is wrong:
DISTANCE INCLUDE FILE=options.dat
RESTRAINT ARG=dist
10.5.1
INCLUDE
This is part of the generic module
Includes an external input file, similar to "#include" in C preprocessor.
Useful to split very large plumed.dat files. Notice that in PLUMED 2.4 this action cannot be used before the initial
setup part of the file (e.g. in the part with UNITS, MOLINFO, etc). As of PLUMED 2.5, INCLUDE can be used in
any position of the file.
Compulsory keywords
FILE
file to be included
Generated by Doxygen
10.5 Including other files
653
Examples
This input:
BEGIN_PLUMED_FILE
c1: COM ATOMS=1-100
c2: COM ATOMS=101-202
d: DISTANCE ATOMS=c1,c2
PRINT ARG=d
can be replaced with this input:
BEGIN_PLUMED_FILE
INCLUDE FILE=pippo.dat
d: DISTANCE ATOMS=c1,c2
PRINT ARG=d
where the content of file pippo.dat is
BEGIN_PLUMED_FILE
c1: COM ATOMS=1-100
c2: COM ATOMS=101-202
The files in this example are rather short, but imagine a case like this one:
BEGIN_PLUMED_FILE
INCLUDE FILE=groups.dat
c: COORDINATION GROUPA=groupa GROUPB=groupb R_0=0.5
METAD ARG=c HEIGHT=0.2 PACE=100 SIGMA=0.2 BIASFACTOR=5
Here groups.dat could be huge file containing group definitions such as
BEGIN_PLUMED_FILE
groupa: GROUP ...
ATOMS={
10
50
60
## imagine a long list here
70
80
120
}
...
groupb: GROUP ...
ATOMS={
11
51
61
## imagine a long list here
71
81
121
}
...
So, included files are the best place where one can store long definitions.
Another case where INCLUDE is very 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 have common.dat:
Generated by Doxygen
654
Miscelaneous
BEGIN_PLUMED_FILE
# this is common.dat
t: TORSION ATOMS=1,2,3,4
Then plumed.0.dat:
BEGIN_PLUMED_FILE
# this is plumed.0.dat
INCLUDE FILE=common.dat
RESTRAINT ARG=t AT=1.0 KAPPA=10
And plumed.1.dat:
BEGIN_PLUMED_FILE
# this is plumed.1.dat
INCLUDE FILE=common.dat
RESTRAINT ARG=t AT=1.2 KAPPA=10
Warning
Remember that when using multi replica simulations whenever plumed tried to open a file for reading it looks
for a file with the replica suffix first. This is true also for files opened by INCLUDE!
As an example, the same result of the inputs above could have been obtained using plumed.dat:
BEGIN_PLUMED_FILE
# this is plumed.dat
t: TORSION ATOMS=1,2,3,4
INCLUDE FILE=other.dat
Then other.0.dat:
BEGIN_PLUMED_FILE
# this is other.0.dat
RESTRAINT ARG=t AT=1.0 KAPPA=10
And other.1.dat:
BEGIN_PLUMED_FILE
# this is other.1.dat
RESTRAINT ARG=t AT=1.2 KAPPA=10
10.6
Loading shared libraries
You can introduce new functionality into PLUMED by placing it directly into the src directory and recompiling the
PLUMED libraries. Alternatively, if you want to keep your code independent from the rest of PLUMED (perhaps so
you can release it independently - we won't be offended), then you can create your own dynamic library. To use this
in conjunction with PLUMED you can then load it at runtime by using the LOAD keyword as shown below:
BEGIN_PLUMED_FILE
LOAD FILE=library.so
N.B. If your system uses a different suffix for dynamic libraries (e.g. macs use .dylib) then PLUMED will try to
automatically adjust the suffix accordingly.
10.6.1
LOAD
Generated by Doxygen
10.6 Loading shared libraries
655
This is part of the setup module
Loads a library, possibly defining new actions.
It is available only on systems allowing for dynamic loading. It can also be fed with a cpp file, in which case the file
is compiled first.
Compulsory keywords
FILE
file to be loaded
Examples
If you have a shared object named extensions.so and want to use the functionalities implemented in it within PL←UMED you can load it with the following syntax
BEGIN_PLUMED_FILE
LOAD FILE=extensions.so
As a more practical example, imagine that you want to make a small change to one collective variable that is
already implemented in PLUMED, say DISTANCE . Copy the file src/colvar/Distance.cpp into your work
directory, rename it as Distance2.cpp and edit it as you wish. It might be better to also replace any occurrence
of the string DISTANCE within the file with DISTANCE2, so that both old and new implementation will be available
with different names. Then you can compile it into a shared object using
> plumed mklib Distance2.cpp
This will generate a file Distance2.so (or Distance2.dylib on a mac) that can be loaded. Now you can
use your new implementation with the following input
BEGIN_PLUMED_FILE
# load the new library
LOAD FILE=Distance2.so
# compute standard distance
d: DISTANCE ATOMS=1,10
# compute modified distance
d2: DISTANCE2 ATOMS=1,10
# print them on a file
PRINT ARG=d,d2 FILE=compare-them
You can even skip the initial step and directly feed PLUMED with the Distance2.cpp file: it will be compiled on
the fly.
BEGIN_PLUMED_FILE
# load the new definition
# this is a cpp file so it will be compiled
LOAD FILE=Distance2.cpp
# compute standard distance
d: DISTANCE ATOMS=1,10
# compute modified distance
d2: DISTANCE2 ATOMS=1,10
# print them on a file
PRINT ARG=d,d2 FILE=compare-them
This will allow to make quick tests while developing your own variables. Of course, after your implementation is
ready you might want to add it to the PLUMED source tree and recompile the whole PLUMED.
Generated by Doxygen
656
Miscelaneous
10.7
Embed a separate PLUMED instance
PLUMED
10.7.1
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.
Generated by Doxygen
10.7 Embed a separate PLUMED instance
657
• 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.
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
Examples
Here an example plumed file:
BEGIN_PLUMED_FILE
# plumed.dat
p: PLUMED FILE=plumed2.dat
PRINT ARG=p.bias FILE=COLVAR
plumed2.dat can be an arbitrary plumed input file, for instance
Generated by Doxygen
658
Miscelaneous
BEGIN_PLUMED_FILE
# plumed2.dat
d: DISTANCE ATOMS=1,10
RESTRAINT ARG=d KAPPA=10 AT=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:
BEGIN_PLUMED_FILE
# plumed.dat
PLUMED FILE=plumed.dat CHDIR=directory1
PLUMED FILE=plumed.dat CHDIR=directory2
10.8
Debugging the code
The DEBUG action provides some functionality for debugging the code that may be useful if you are doing very
intensive development of the code of if you are running on a computer with a strange architecture.
10.8.1
DEBUG
This is part of the generic module
Set some debug options.
Can be used while debugging or optimizing plumed.
Compulsory keywords
STRIDE
( default=1 ) the frequency with which this action is to be performed
Options
logActivity
( default=off ) write in the log which actions are inactive and which are inactive
logRequestedAtoms
( default=off ) write in the log which atoms have been requested at a given time
NOVIRIAL
( default=off ) switch off the virial contribution for the entirety of the simulation
DETAILED_TIMERS
( default=off ) switch on detailed timers
FILE
the name of the file on which to output these quantities
Generated by Doxygen
10.9 Changing exchange patterns in replica exchange
659
Examples
BEGIN_PLUMED_FILE
# print detailed (action-by-action) timers at the end of simulation
DEBUG DETAILED_TIMERS
# dump every two steps which are the atoms required from the MD code
DEBUG logRequestedAtoms STRIDE=2
10.9
Changing exchange patterns in replica exchange
Using the RANDOM_EXCHANGES keyword it is possible to make exchanges between randomly chosen replicas.
This is useful e.g. for bias exchange metadynamics [96].
10.9.1
RANDOM_EXCHANGES
This is part of the generic module
Set random pattern for exchanges.
In this way, exchanges will not be done between replicas with consecutive index, but will be done using a random
pattern. Typically used in bias exchange [96].
Options
SEED
seed for random exchanges
Examples
Using the following three input files one can run a bias exchange metadynamics simulation using a different angle
in each replica. Exchanges will be randomly tried between replicas 0-1, 0-2 and 1-2
Here is plumed.0.dat
BEGIN_PLUMED_FILE
RANDOM_EXCHANGES
t: TORSION ATOMS=1,2,3,4
METAD ARG=t HEIGHT=0.1 PACE=100 SIGMA=0.3
Here is plumed.1.dat
BEGIN_PLUMED_FILE
RANDOM_EXCHANGES
t: TORSION ATOMS=2,3,4,5
METAD ARG=t HEIGHT=0.1 PACE=100 SIGMA=0.3
Generated by Doxygen
660
Miscelaneous
Here is plumed.2.dat
BEGIN_PLUMED_FILE
RANDOM_EXCHANGES
t: TORSION ATOMS=3,4,5,6
METAD ARG=t HEIGHT=0.1 PACE=100 SIGMA=0.3
Warning
Multi replica simulations are presently only working with gromacs.
The directive should appear in input files for every replicas. In case SEED is specified, it should be the same
in all input files.
10.10
List of modules
The functionality in PLUMED 2 is divided into a small number of modules. Some users may only wish to use a
subset of the functionality available within the code while others may wish to use some of the more complicated
features that are available. For this reason the plumed source code is divided into modules, which users can activate
or deactivate to their hearts content.
You can activate a module at configure time using the keyword --enable-modules. For example:
./configure --enable-modules=modulename
will enable module called modulename. A module that is on by default can be disabled using the following syntax
./configure --enable-modules=-modulename
To enable or disable multiple modules one should provide them as a : separated list. Notice that +modulename
and modulename both activate the module, whereas -modulename deactivates it. E.g.
./configure --enable-modules=+crystallization:-colvar
will disable the colvar module and enable the crystallization module. Also notice that : can be omitted when using
+ or -. Thus, the same can be obtained with
./configure --enable-modules=+crystallization-colvar
If you repeat the --enable-modules keyword only the last instance will be used. Thus ./configure
--enable-modules=crystallization --enable-modules=-colvar will not do what you expect!
There are also some shortcuts available:
• ./configure --enable-modules=all to enable all optional modules. This includes the maximum
number of features in PLUMED, including modules that might not be properly functional.
• ./configure --enable-modules=none or ./configure --disable-modules to disable
all optional modules. This produces a minimal PLUMED which can be used as a library but which has no
command line tools and no collective variables or biasing methods.
• ./configure --enable-modules=reset or ./configure --enable-modules to enable
the default modules.
The two kinds of syntax can be combined and, for example, ./configure --enable-modules=none←:colvar will result in a PLUMED with all the modules disabled with the exception of the colvar module.
Some modules are active by default in the version of PLUMED 2 that you download from the website while others
are inactive. The following lists all of the modules that are available in plumed and tells you whether or not they are
active by default.
Generated by Doxygen
10.11 Special replica syntax
661
Module name
adjmat
Default behavior
off
analysis
on
bias
cltools
colvar
crystallization
on
on
on
off
dimred
drr
eds
function
generic
off
off
off
on
on
isdb
logmfd
on
off
manyrestraints
off
mapping
on
maze
molfile
multicolvar
pamm
off
on
on
off
piv
off
secondarystructure
on
setup
on
vatom
ves
on
off
Until PLUMED 2.2, it was also possible to switch on or off modules by adding files in the plumed2/src directory. Since PLUMED 2.3 this is discouraged, since any choice made in this manner will be overwritten next time
./configure is used.
10.11
Special replica syntax
(this part of the manual is based on Using special syntax for multiple replicas).
In many cases, we need to run multiple replicas with almost identical PLUMED files. These files might be prepared
with cut-and-paste, which is very error prone, or could be set up with some smart bash or python script. Additionally,
one can take advantage of the INCLUDE keyword so as to have a shared input file with common definitions and
specific input files with replica-dependent keywords. However, as of PLUMED 2.4, we introduced a simpler manner
to manipulate multiple replica inputs with tiny differences. Look at the following example:
BEGIN_PLUMED_FILE
# Compute a distance
d: DISTANCE ATOMS=1,2
# Apply a restraint.
RESTRAINT ARG=d AT=@replicas:1.0,1.1,1.2 KAPPA=1.0
# On replica 0, this means:
#
RESTRAINT ARG=d AT=1.0 KAPPA=1.0
# On replica 1, this means:
#
RESTRAINT ARG=d AT=1.1 KAPPA=1.0
# On replica 2, this means:
#
RESTRAINT ARG=d AT=1.2 KAPPA=1.0
Generated by Doxygen
662
Miscelaneous
If you prepare a single plumed.dat file like this one and feeds it to PLUMED while using 3 replicas, the 3 replicas
will see the very same input except for the AT keyword, that sets the position of the restraint. Replica 0 will see a
restraint centered at 1.0, replica 1 centered at 1.1, and replica 2 centered at 1.2.
The @replicas: keyword is not special for RESTRAINT or for the AT keyword. Any keyword in PLUMED can
accept that syntax. For instance, the following single input file can be used to setup a bias exchange metadynamics
[96] simulations:
BEGIN_PLUMED_FILE
# Compute distance between atoms 1 and 2
d: DISTANCE ATOMS=1,2
# Compute a torsional angle
t: TORSION ATOMS=30,31,32,33
# Metadynamics.
METAD ...
ARG=@replicas:d,t
HEIGHT=1.0
PACE=100
SIGMA=@replicas:0.1,0.3
GRID_MIN=@replicas:0.0,-pi
GRID_MAX=@replicas:2.0,+pi
...
# On replica 0, this means:
# METAD ARG=d HEIGHT=1.0 PACE=100 SIGMA=0.1 GRID_MIN=0.0 GRID_MAX=2.0
# On replica 1, this means:
# METAD ARG=t HEIGHT=1.0 PACE=100 SIGMA=0.3 GRID_MIN=-pi GRID_MAX=+pi
This would be a typical setup for a bias exchange simulation. Notice that even though variables d and t are both
read in both replicas, d is only computed on replica 0 (and t is only computed on replica 1). This is because
variables that are defined but not used are never actually calculated by PLUMED.
If the value that should be provided for each replica is a vector, you should use curly braces as delimiters. For
instance, if the restraint acts on two variables, you can use the following input:
BEGIN_PLUMED_FILE
# Compute distance between atoms 1 and 2
d: DISTANCE ATOMS=10,20
# Compute a torsional angle
t: TORSION ATOMS=30,31,32,33
# Apply a restraint:
RESTRAINT ...
ARG=d,t
AT=@replicas:{{1.0,2.0} {3.0,4.0} {5.0,6.0}}
KAPPA=1.0,3.0
...
# On replica 0 this means:
# RESTRAINT ARG=d AT=1.0,2.0 KAPPA=1.0,3.0
# On replica 1 this means:
# RESTRAINT ARG=d AT=3.0,4.0 KAPPA=1.0,3.0
# On replica 2 this means:
# RESTRAINT ARG=d AT=5.0,6.0 KAPPA=1.0,3.0
Notice the double curly braces. The outer ones are used by PLUMED to know there the argument of the AT keyword
ends, whereas the inner ones are used to group the values corresponding to each replica. Also notice that the last
example can be split in multiple lines exploiting the fact that within multi-line statements (enclosed by pairs of ...)
newlines are replaced with simple spaces:
BEGIN_PLUMED_FILE
d: DISTANCE ATOMS=10,20
t: TORSION ATOMS=30,31,32,33
RESTRAINT ...
ARG=d,t
Generated by Doxygen
10.13 Frequently used tools
663
# indentation is not required (this is not python!)
# but makes the input easier to read
AT=@replicas:{
{1.0,2.0}
{3.0,4.0}
{5.0,6.0}
}
KAPPA=1.0
...
In short, whenever there are keywords that should vary across replicas, you should set them using the
@replicas: keyword. As mentioned above, you can always use the old syntax with separate input file,
and this is recommended when the number of keywords that are different is large.
10.12
Parsing constants
You might have noticed that from time to time constants are specified using strings rather than numbers. An example
is the following
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=AA.pdb MOLTYPE=rna
e1: TORSION ATOMS=@epsilon-1
t: METAD ARG=e1 SIGMA=0.15 PACE=10 HEIGHT=2 GRID_MIN=-pi GRID_MAX=pi GRID_BIN=200
Notice that the boundaries for GRID_MIN and GRID_MAX are -pi and pi. Until PLUMED 2.3, we used a very
dummy parses that could recognize only pi as a special string, plus strings such as 0.5pi and -pi. However,
as of version 2.4, we use the Lepton library in order to parse every constant that we read. This means that you can
also employ more complicated expressions such as 1+2 or exp(10):
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=AA.pdb MOLTYPE=rna
e1: TORSION ATOMS=@epsilon-1
RESTRAINT ARG=e1 AT=1+0.5
Notice that this applies to any quantity read by plumed as a real number, but does not apply yet to integer numbers
(e.g.: the PACE argument of METAD).
10.13
Frequently used tools
histogrambead
INTERNAL
A function that can be used to calculate whether quantities are between fixed
upper and lower bounds.
kernelfunctions
INTERNAL
Functions that are used to construct histograms
pdbreader
INTERNAL
PLUMED can use the PDB format in several places
switchingfunction
INTERNAL
Functions that measure whether values are less than a certain quantity.
Regular Expressions
POSIX regular expressions can be used to select multiple actions when using ARG
(i.e. PRINT).
Files
Dealing with Input/Output
Generated by Doxygen
664
10.13.1
Miscelaneous
histogrambead
A function that can be used to calculate whether quantities are between fixed upper and lower bounds. A function
that can be used to calculate whether quantities are between fixed upper and lower bounds.
If we have multiple instances of a variable we can estimate the probability density function for that variable using a
process called kernel density estimation:
X
P (s) =
K
i
s − si
w
In this equation K is a symmetric function that must integrate to one that is often called a kernel function and w is a
smearing parameter. From a probability density function calculated using kernel density estimation we can calculate
the number/fraction of values between an upper and lower bound using:
Z
b
w(s) =
a
X
K
i
s − si
w
All the input to calculate a quantity like w(s) is generally provided through a single keyword that will have the
following form:
KEYWORD={TYPE UPPER= a LOWER= b SMEAR=
w
b−a }
This will calculate the number of values between a and b. To calculate the fraction of values you add the word
NORM to the input specification. If the function keyword SMEAR is not present w is set equal to 0.5(b − a). Finally,
type should specify one of the kernel types that is present in plumed. These are listed in the table below:
TYPE
FUNCTION
GAUSSIAN
√1
2πw
TRIANGULAR
1
2w
2
i)
exp − (s−s
2
2w
s−si
s−si
1. − w
w <1
Some keywords can also be used to calculate a discrete version of the histogram. That is to say the number of
values between a and b, the number of values between b and c and so on. A keyword that specifies this sort of
calculation would look something like
KEYWORD={TYPE UPPER= a LOWER= b NBINS= n SMEAR=
w
n(b−a) }
This specification would calculate the following vector of quantities:
Z
wj (s) =
10.13.2
j
a+ n
(b−a)
a+ j−1
n (b−a)
X
i
K
s − si
w
kernelfunctions
Functions that are used to construct histograms Functions that are used to construct histograms
Generated by Doxygen
10.13 Frequently used tools
665
Constructing histograms is something you learned to do relatively early in life. You perform an experiment a number
of times, count the number of times each result comes up and then draw a bar graph that describes how often each
of the results came up. This only works when there are a finite number of possible results. If the result a number
between 0 and 1 the bar chart is less easy to draw as there are as many possible results as there are numbers
between zero and one - an infinite number. To resolve this problem we replace probability, P with probability density,
π , and write the probability of getting a number between a and b as:
b
Z
dxπ(x)
P =
a
To calculate probability densities from a set of results we use a process called kernel density estimation. Histograms
are accumulated by adding up kernel functions, K , with finite spatial extent, that integrate to one. These functions
are centered on each of the n-dimensional data points, xi . The overall effect of this is that each result we obtain in
our experiments contributes to the probability density in a finite sized region of the space.
Expressing all this mathematically in kernel density estimation we write the probability density as:
π(x) =
X
K (x − xi )T Σ(x − xi )
i
where Σ is an n × n matrix called the bandwidth that controls the spatial extent of the kernel. Whenever we
accumulate a histogram (e.g. in HISTOGRAM or in METAD) we use this technique.
There is thus some flexibility in the particular function we use for K[r] in the above. The following variants are
available.
TYPE
FUNCTION
gaussian
f (r) =
truncated-gaussian
f (r) =
triangular
f (r) =
uniform
f (r) =
(2π)n
(2π)n
3
V
1
V
1
√
√
|Σ−1 |
exp −0.5r2
1
(
|Σ−1 |
erf(−6.25/sqrt2)−erf(−6.25/sqrt2)
2
n
)
exp −0.5r2
(1 − |r|)H(1 − |r|)
H(1 − |r|)
In the above H(y) is a function that is equal to one when y > 0 and zero when y ≤ 0. n is the dimensionality of
the vector x and V is the volume of an ellipse in an n dimensional space which is given by:
n
V
=
|Σ−1 |
π2
n
2
V
=
|Σ−1 |
2
!
n+1
2
π
n!!
for even
n
n−1
2
In METAD the normalization constants are ignored so that the value of the function at r = 0 is equal to one. In
addition in METAD we must be able to differentiate the bias in order to get forces. This limits the kernels we can
use in this method. Notice also that Gaussian kernels should have infinite support. When used with grids, however,
they are assumed to only be non-zero over a finite range. The difference between the truncated-gaussian and
regular gaussian is that the truncated gaussian is scaled so that its integral over the grid is equal to one when it is
normalized. The integral of a regular gaussian when it is evaluated on a grid will be slightly less that one because
of the truncation of a function that should have infinite support.
Generated by Doxygen
666
Miscelaneous
10.13.3
pdbreader
PLUMED can use the PDB format in several places PLUMED can use the PDB format in several places
• To read molecular structure (MOLINFO).
• To read reference conformations (RMSD, but also many other methods in Distances from reference configurations,
FIT_TO_TEMPLATE, etc).
The implemented PDB reader expects a file formatted correctly according to the PDB standard. In particular,
the following columns are read from ATOM records
columns
1-6
7-11
13-16
18-20
22
23-26
31-38
39-46
47-54
55-60
61-66
|
|
|
|
|
|
|
|
|
|
|
|
content
record name (ATOM or HETATM)
serial number of the atom (starting from 1)
atom name
residue name
chain id
residue number
x coordinate
y coordinate
z coordinate
occupancy
beta factor
PLUMED parser is slightly more permissive than the official PDB format in the fact that the format of real numbers is
not fixed. In other words, any real number that can be parsed is OK and the dot can be placed anywhere. However,
columns are interpret strictly. A sample PDB should look like the following
ATOM
ATOM
ATOM
2
5
9
CH3 ACE
C
ACE
CA ALA
1
1
2
12.932 -14.718
21.312 -9.928
19.462 -11.088
-6.016
-5.946
-8.986
1.00
1.00
1.00
1.00
1.00
1.00
Notice that serial numbers need not to be consecutive. In the three-line example above, only the coordinates of
three atoms are provided. This is perfectly legal and indicates PLUMED that information about these atoms only is
available. This could be both for structural information in MOLINFO, where the other atoms would have no name
assigned, and for reference structures used in RMSD, where only the provided atoms would be used to compute
RMSD.
Occupancy and beta factors
PLUMED reads also occupancy and beta factors that however are given a very special meaning. In cases
where the PDB structure is used as a reference for an alignment (that's the case for instance in RMSD and in
FIT_TO_TEMPLATE), the occupancy column is used to provide the weight of each atom in the alignment. In cases
where, perhaps after alignment, the displacement between running coordinates and the provided PDB is computed,
the beta factors are used as weight for the displacement. Since setting the weights to zero is the same as not
including an atom in the alignment or displacement calculation, the two following reference files would be equivalent
when used in an RMSD calculation. First file:
ATOM
ATOM
ATOM
2
5
9
CH3 ACE
C
ACE
CA ALA
1
1
2
12.932 -14.718
21.312 -9.928
19.462 -11.088
-6.016
-5.946
-8.986
1.00
1.00
0.00
1.00
1.00
0.00
2
5
CH3 ACE
C
ACE
1
1
12.932 -14.718
21.312 -9.928
-6.016
-5.946
1.00
1.00
1.00
1.00
Second file:
ATOM
ATOM
Generated by Doxygen
10.13 Frequently used tools
667
However notice that many extra atoms with zero weight might slow down the calculation, so removing lines is
better than setting their weights to zero. In addition, weights for alignment need not to be equivalent to weights for
displacement.
Systems with more than 100k atoms
Notice that it very likely does not make any sense to compute the RMSD or any other structural deviation using so
many atoms. However, if the protein for which you want to compute RMSD has atoms with large serial numbers
(e.g. because it is located after solvent in the sorted list of atoms) you might end up with troubles with the limitations
of the PDB format. Indeed, since there are 5 columns available for atom serial number, this number cannot be larger
than 99999. In addition, providing MOLINFO with names associated to atoms with a serial larger than 99999 would
be impossible.
Since PLUMED 2.4 we allow hybrid 36 format to be used to specify atom numbers. This format is not particularly
widespread, but has the nice feature that it provides a one-to-one mapping between numbers up to approximately
80 millions and strings with 5 characters, plus it is backward compatible for numbers smaller than 100000. This is
not true for notations like the hex notation exported by VMD. Using the hybrid 36 format, the ATOM records for atom
ranging from 99997 to 100002 would read like these:
ATOM
ATOM
ATOM
ATOM
ATOM
ATOM
99997
99998
99999
A0000
A0000
A0001
Ar
Ar
Ar
Ar
Ar
Ar
X
X
X
X
X
X
1
1
1
1
1
1
45.349
46.189
46.189
45.349
45.349
46.189
38.631
38.631
39.471
39.471
38.631
38.631
15.116
15.956
15.116
15.956
16.796
17.636
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
1.00
There are tools that can be found to translate from integers to strings and back using hybrid 36 format (a simple
python script can be found here). In addition, as of PLUMED 2.5, we provide a command line tool that can be
used to renumber atoms in a PDB file.
10.13.4
switchingfunction
Functions that measure whether values are less than a certain quantity. Functions that measure whether values are
less than a certain quantity.
Switching functions s(r) take a minimum of one input parameter d0 . For r ≤ d0 s(r) = 1.0 while for r > d0 the
function decays smoothly to 0. The various switching functions available in plumed differ in terms of how this decay
is performed.
Where there is an accepted convention in the literature (e.g. COORDINATION) on the form of the switching function
we use the convention as the default. However, the flexibility to use different switching functions is always present
generally through a single keyword. This keyword generally takes an input with the following form:
KEYWORD={TYPE }
The following table contains a list of the various switching functions that are available in plumed 2 together with an
example input.
Generated by Doxygen
668
Miscelaneous
TYPE
FUNCTION
EXAMPLE INPUT
DEFAULT PARAMETE←RS
RATIONAL
s(r) =
{RATIONAL R_0= r0 D←_0= d0 NN= n MM= m}
d0 = 0.0, n = 6, m =
2n
{EXP R_0= r0 D_0= d0 }
d0 = 0.0
{GAUSSIAN R_0= r0 D←_0= d0 }
d0 = 0.0
SMAP
s(r)
= {SMAP R_0= r0 D_0= d0
a i−b/a
h
A= a B= b}
r−d0
a/b
1 + (2 − 1) r0
d0 = 0.0
Q
s(r)
r−d0 n
1−
r
0 m
r−d0
1−
r
0
EXP
GAUSSIAN
0
s(r) = exp − r−d
r0
2
0)
s(r) = exp − (r−d
2
2r
0
=
1
0 ))
1+exp(β(rij −λrij
CUBIC
s(r) = (y − 1)2 (1 +
2y)
where y
=
0
{Q REF= rij
BETA= β
LAMBDA= λ }
λ = 1.8, β = 50nm− 1
(all-atom)
λ = 1.5, β = 50nm− 1
(coarse-grained)
{CUBIC D_0= r1 D_M←AX= r0 }
r−r1
r0 −r1
TANH
s(r) = 1 − tanh
r−d0
r0
COSINUS
{TANH R_0= r0 D_0= d0 }
=1
if d0 d
the switching function can be assumed equal to zero. In
this case the function is brought smoothly to zero by stretching and shifting it.
max
Generated by Doxygen
10.13 Frequently used tools
669
KEYWORD={RATIONAL R_0=1 D_MAX=3}
s0 (r)−s0 (d
)
6
1−r
the resulting switching function will be s(r) = s0 (0)−s0 (dmax
where s0 (r) = 1−r
12 Since PLUMED 2.2 this is the
max )
default. The old behavior (no stretching) can be obtained with the NOSTRETCH flag. The NOSTRETCH keyword
is only provided for backward compatibility and might be removed in the future. Similarly, the STRETCH keyword is
still allowed but has no effect.
Notice that switching functions defined with the simplified syntax are never stretched for backward compatibility.
This might change in the future.
10.13.5
Regular Expressions
When you use need to pass many arguments to a PLUMED action, being them components of a few collective
variables or also multiple collective variables, you might find it convenient to use regular expressions.
Since version 2.1, plumed takes advantage of a configuration scripts that detects libraries installed on your system.
If regex library is found, then you will be able to use regular expressions to refer to collective variables or function
names.
Regular expressions are enclosed in round braces and must not contain spaces (the components names have no
spaces indeed, so why use them?).
As an example the command:
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=1,2 COMPONENTS
PRINT ARG=(d1\.[xy])
STRIDE=100 FILE=colvar FMT=%8.4f
will cause both the d1.x and d1.y components of the DISTANCE action to be printed.
Notice that selection does not happen in alphabetic order, nor in the order in which [xy] are listed, but rather in the
order in which the two variables have been created by PLUMED. Also notice that the . character must be escaped
as \. in order to interpret it as a literal .. An un-escaped dot is a wildcard which is matched by any character, So
as an example
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=1,2 COMPONENTS
dxy: DISTANCE ATOMS=1,3
# this will match d1.x,d1.y,dxy
PRINT ARG=(d1.[xy])
STRIDE=100 FILE=colvar FMT=%8.4f
# while this will match d1.x,d1.y only
PRINT ARG=(d1\.[xy])
STRIDE=100 FILE=colvar FMT=%8.4f
You can concatenate more than one regular expression by using comma separated regular expressions. The
resulting matches will be concatenated:
BEGIN_PLUMED_FILE
t1: TORSION ATOMS=5,7,9,15
t2: TORSION ATOMS=7,9,15,17
d1: DISTANCE ATOMS=7,17 COMPONENTS
# The first expression matches d1.x and d1.y
# The second expression matches t1 and t2
PRINT ARG=(d1\.[xy]),(t[0-9]) STRIDE=100 FILE=colvar FMT=%8.4f
# Thus this is the same as ARG=d1.x,d1.y,t1,t2
Generated by Doxygen
670
Miscelaneous
Be aware that if you have overlapping selections they will be duplicated. As an alternative you could use the "or"
operator |:
BEGIN_PLUMED_FILE
t1: TORSION ATOMS=5,7,9,15
t2: TORSION ATOMS=7,9,15,17
d1: DISTANCE ATOMS=7,17 COMPONENTS
# Here is a single regular expression
PRINT ARG=(d1\.[xy]|t[0-9]) STRIDE=100 FILE=colvar FMT=%8.4f
# Thus this is the same as ARG=t1,t2,d1.x,d1.y
this selects the same set of arguments as the previous example.
Note
Be careful you do not confuse regular expressions, which are triggered by the parenthesis () and only available when PLUMED has been compiled with the regex library, with the capability of PLUMED to use ∗ as a
wildcard in arguments:
BEGIN_PLUMED_FILE
d1: DISTANCE ATOMS=1,2 COMPONENTS
# this is a regular expression that selects all components of d1
# i.e. d1.x d1.y and d1.z
PRINT ARG=(d1\..*)
STRIDE=100 FILE=colvar_reg FMT=%8.4f
# this is a wildcard that selects all the components of d1 as well
PRINT ARG=d1.*
STRIDE=100 FILE=colvar_wild FMT=%8.4f
Regular expressions are way more flexible than wildcards!
You can check the log to see whether or not your regular expression is picking the set of components you desire.
For more information on regular expressions visit http://www.regular-expressions.info/reference.←-
html.
10.13.6
Files
We tried to design PLUMED in such a manner that input/output is done consistently irrespective of the file type.
Most of the files written or read by PLUMED thus follow the very same conventions discussed below.
10.13.6.1
Restart
Whenever the RESTART option is used, all the files written by PLUMED are appended. This makes it easy to
analyze results of simulations performed as a chain of several sub-runs. Notice that most of the PLUMED textual
files have a header. The header is repeated at every restart. Additionally, several files have time in the first column.
PLUMED just takes the value of the physical time from the MD engine. As such, you could have that time starts
again from zero upon restart or not.
An exception from this behavior is given by files which are not growing as the simulation proceeds. For example,
grids written with METAD with GRID_WFILE are overwritten by default during the simulation. As such, when
restarting, there is no point in appending the file. Internally, PLUMED opens the file in append mode but then
rewinds it every time a new grid is dumped.
Generated by Doxygen
10.13 Frequently used tools
10.13.6.2
671
Backup
Whenever the RESTART option is not used, PLUMED tries to write new files. If an old file is found in the way, P←LUMED takes a backup named "bck.X.filename" where X is a progressive number. Notice that by default PLUMED
only allows a maximum of 100 backup copies for a file. This behavior can be changed by setting the environment
variable PLUMED_MAXBACKUP to the desired number of copies. E.g. export PLUMED_MAXBACKUP=10 will fail
after 10 copies. PLUMED_MAXBACKUP=-1 will never fail - be careful since your disk might fill up quickly with this
setting.
10.13.6.3
Replica suffix
When running with multiple replicas (e.g., with GROMACS, -multi option) PLUMED adds the replica index as a
suffix to all the files. The following command will thus print files named COLVAR.0, COLVAR.1, etc for the different
replicas.
BEGIN_PLUMED_FILE
d: DISTANCE ATOMS=1,2
PRINT ARG=d FILE=COLVAR
When reading a file, PLUMED will try to add the suffix. If the file is not found, it will fall back to the name without
suffix. The most important case is the reading of the plumed input file. If you provide a file for each replica (e.g.
plumed.0.dat, plumed.1.dat, etc) you will be able to setup plumed differently on each replica. On the other hand,
using a single plumed.dat will make all the replicas read the same file.
Warning
This rule is true for almost all the files read by PLUMED. As of PLUMED version 2.4, the only exception is
PDB files, where the replica suffix is not added.
Notice that when PLUMED adds the replica suffix, it recognizes the file extension and add the suffix before the
extension. Before PLUMED 2.2, the only recognized suffix was ".gz". Since 2.2, any suffix with length less or equal
to five letters is recognized.
This means that using in a multi-replica context an input such as
BEGIN_PLUMED_FILE
d: DISTANCE ATOMS=1,2
PRINT ARG=d FILE=COLVAR.gz
METAD ARG=d FILE=test.HILLS SIGMA=0.1 HEIGHT=0.1
PLUMED will write files named COLVAR.0.gz, COLVAR.1.gz, test.0.HILLS, test.1.HILLS, etc etc. This is useful
since the preserved extension makes it easy to process the files later.
Generated by Doxygen
672
Miscelaneous
Generated by Doxygen
Chapter 11
Tutorials
The following pages describe how to perform a variety of tasks using PLUMED
Trieste tutorial: Analyzing trajectories using PLUMED
This tutorial explains how to use PLUMED to analyze
trajectories
Trieste tutorial: Averaging, histograms and block analysis Averaging, histograms and block averaging
Trieste tutorial: Using restraints
This tutorial explains how to use PLUMED to run simple restrained simulations and account for the bias in
the analysis
Trieste tutorial: Metadynamics simulations with PLUMED This tutorial explains how to use PLUMED to run metadynamics simulations
Trieste tutorial: Running and analyzing multi-replica simulations.
This tutorial explains how to use PLUMED to run and
analyze multi-replica simulations
Trieste tutorial: Real-life applications with complex CVs
This tutorial explains how to use PLUMED to run metadynamics simulations
Belfast tutorial: Analyzing CVs
Belfast tutorial: Adaptive variables I
This tutorial explains how to use plumed to analyze
CVs
How to use path CVs
Belfast tutorial: Adaptive variables II
Dimensionality reduction and sketch maps
Belfast tutorial: Umbrella sampling
Umbrella sampling, reweighting, and weighted histogram
Belfast tutorial: Out of equilibrium dynamics
How to run a steered MD simulations and how to estimate the free energy
Belfast tutorial: Metadynamics
How to run a metadynamics simulation
Belfast tutorial: Replica exchange I
Parallel tempering and Metadynamics, Well-Tempered
Ensemble
Belfast tutorial: Replica exchange II and Multiple walkers Bias exchange and multiple walkers
Belfast tutorial: NMR restraints
Belfast tutorial: Steinhardt Parameters
Cambridge tutorial
NMR restraints
Steinhardt Parameters
A short 2 hours tutorial that introduces Well-Tempered
Metadynamics, Bias-Exchange Metadynamics and
Replica-Average Metadynamics
CINECA tutorial
A short 2 hours tutorial that introduces analysis, welltempered metadynamics, and multiple-restraints umbrella sampling.
Using Hamiltonian replica exchange with GROMACS
This tutorial explains how to use Hamiltonian replica
exchange in GROMACS
Julich tutorial: Developing CVs in plumed
Implementing new collective variables in plumed
674
Tutorials
Lugano tutorial: Analyzing CVs
This tutorial explains how to use PLUMED to analyze
CVs
Lugano tutorial: Path CVs
This tutorial explains how to use various kinds of path
collective variables
ESDW Workshop Lyon 2019: A very simple introduction to
This
PLUMED
tutorial gives a brief introduction to PLUMED by
showing how it can be used to study a cluster of 7
Lennard Jones atoms.
Moving from PLUMED 1 to PLUMED 2
This tutorial explains how plumed 1 input files can be
translated into the new plumed 2 syntax.
Munster tutorial
A short 3 hours tutorial that introduces analysis, welltempered metadynamics, and multiple-restraints umbrella sampling.
Optimizing PLUMED performance
A short 1.5 hours tutorial that introduces performance
optimization
In addition, the following websites contain resources that might be helpful
http://www.youtube.com/watch?v=iDv←ZmbWE5ps
http://www.youtube.com/watch?v=PxJ←P16qNCYs
http://en.wikipedia.org/wiki/←Metadynamics
A short video introduction to the use of multicolvars in
PLUMED 2
A short video introduction to the syntax of the PLUM←ED 2 input file
A wikipedia article on metadynamics
11.1
Trieste tutorial: Analyzing trajectories using PLUMED
11.1.1
Aims
The aim of this tutorial is to introduce the users to the PLUMED syntax. We will go through the writing of simple
collective variable and we will use them to analyze existing trajectories.
11.1.2
Objectives
Once this tutorial is completed students will be able to:
• Write a simple PLUMED input file and use it with the PLUMED driver to analyze a trajectory.
• Use the GROUP keyword to make the input file compact and easy to read and to quickly build complex atom
groups.
• Print collective variables such as distances (DISTANCE), torsional angles (TORSION), gyration radius
(GYRATION), and coordination numbers (COORDINATION) using the PRINT action.
• Computing the geometric center of a group of atoms using CENTER.
• Know how to take care of periodic boundary conditions within PLUMED using WHOLEMOLECULES and
WRAPAROUND, and be able to verify the result with DUMPATOMS.
• Extract from a trajectory snapshots satisfying specific conditions using UPDATE_IF.
Generated by Doxygen
11.1 Trieste tutorial: Analyzing trajectories using PLUMED
11.1.3
675
Resources
TheTARBALL for this project contains the following files:
• ref.pdb : A PDB file with a RNA duplex solvated in a water box and a Mg ion.
• traj-whole.xtc: A trajectory for the same system in GROMACS xtc format. To make the exercise easier, RNA
duplex has been made whole already.
• traj-broken.xtc: The same trajectory as it was originally produced by GROMACS. Here the RNA duplex is
broken and should be fixed.
This tutorial has been tested on a pre-release version of version 2.4. However, it should not take advantage of
2.4-only features, thus should also work with version 2.3.
Also notice that in the .solutions directory of the tarball you will find correct input files. Please only look at
these files after you have tried to solve the problems yourself.
11.1.4
Introduction
This tutorial asks you to compute a variety of different collective variables using PLUMED for a particular trajectory
and to compare the files and graphs that you obtain with the correct ones that are shown online. Compared to some
of the other tutorials that are available here this tutorial contains considerably less guidance so in doing this tutorial
you will have to learn how to consult the manual. If you would like a more guided introduction to PLUMED it might
be better to start with the tutorials Belfast tutorial: Analyzing CVs or Lugano tutorial: Analyzing CVs.
Also notice that, whereas this tutorial was tested using a pre-release version of PLUMED 2.4, it should be completely
feasible using PLUMED 2.3.
11.1.5
Using PLUMED from the command line
As we will see later, PLUMED provides a library that can be combined with multiple MD codes. However, in this
tutorial we will only use PLUMED to analyze trajectories that have been produced already. Once PLUMED is
installed you can run a plumed executable that can be used for multiple purposes:
> plumed --help
Here we will use the driver tool, that allows you to process an already existing trajectory.
> plumed driver --help
What we will need is:
• A trajectory to be analyzed (provided).
• A PLUMED input file (you do it!).
The syntax of the PLUMED input file is the same that we will use later to run enhanced sampling simulations, so
all the things that you will learn now will be useful later when you will run PLUMED coupled to an MD code. In the
following we are going to see how to write an input file for PLUMED.
Generated by Doxygen
676
Tutorials
11.1.6
The structure of a PLUMED input file
The main goal of PLUMED is to compute collective variables, which are complex descriptors than can be used to
analyze a conformational change or a chemical reaction. This can be done either on the fly, that is during molecular
dynamics, or a posteriori, using PLUMED as a post-processing tool. In both cases one should create an input file
with a specific PLUMED syntax. A sample input file is below:
BEGIN_PLUMED_FILE
# this is optional and tell to VIM that this is a PLUMED file
# vim: ft=plumed
# see comments just below this input file
# Compute distance between atoms 1 and 10.
# Atoms are ordered as in the trajectory files and their numbering starts from 1.
# The distance is called "d" for future reference.
d: DISTANCE ATOMS=1,10
# Create a virtual atom in the center between atoms 20 and 30.
# The virtual atom only exists within PLUMED and is called "center" for future reference.
center: CENTER ATOMS=20,30
# Compute the torsional angle between atoms 1, 10, 20, and center.
# Notice that virtual atoms can be used as real atoms here.
# The angle is called "phi" for future reference.
phi: TORSION ATOMS=1,10,20,center
# Compute some function of previously computed variables.
# In this case we compute the cosine of angle phi and we call it "d2"
d2: MATHEVAL ...
ARG=phi FUNC=cos(x)
PERIODIC=NO
...
# The previous command has been split in multiple lines.
# It could have been equivalently written in a single line:
#
d2: MATHEVAL ARG=phi FUNC=cos(x) PERIODIC=NO
# Print d and d2 every 10 step on a file named "COLVAR1".
PRINT ARG=d,d2 STRIDE=10 FILE=COLVAR1
# Print phi on another file names "COLVAR2" every 100 steps.
PRINT ARG=phi STRIDE=100 FILE=COLVAR2
Note
If you are a VIM user, you might find convenient configuring PLUMED syntax files, see Using VIM syntax file.
Syntax highlighting is particularly useful for beginners since it allows you to identify simple mistakes without
the need to run PLUMED. In addition, VIM has a full dictionary of available keywords and can help you by
autocomplete your commands.
In the input file above, each line defines a so-called action. An action could either compute a distance, or the center
between two or more atoms, or print some value on a file. Each action supports a number of keywords, whose value
is specified. Action names are highlighted in green and, clicking on them, you can go to the corresponding page in
the manual that contains a detailed description for each keyword. Actions that support the keyword STRIDE are
those that determine how frequently things are to be done. Notice that the default value for STRIDE is always 1. In
the example above, omitting STRIDE keywords the corresponding COLVAR files would have been written for every
frame of the analyzed trajectory. All the other actions in the example above do not support the STRIDE keyword
and are only calculated when requested. That is, d and d2 will be computed every 10 frames, and phi every 100
frames. In short, you can think that for every snapshot in the trajectory that you are analyzing PLUMED is going to
execute all the listed actions, though some of them are optimized out when STRIDE is different from 1.
Also notice that PLUMED works using kJ/nm/ps as energy/length/time units. This can be personalized using UNITS,
but we will here stay with default values.
Generated by Doxygen
11.1 Trieste tutorial: Analyzing trajectories using PLUMED
677
Variables should be given a name (in the example above, d, phi, and d2), which is then used to refer to these
variables. Instead of a: DISTANCE ATOMS=1,2 you might equivalently use DISTANCE ATOMS=1,2 L←ABEL=a. Lists of atoms should be provided as comma separated numbers, with no space. Virtual atoms can be
created and assigned a name for later use.
You can find more information on the PLUMED syntax at Getting Started page of the manual. The complete documentation for all the supported collective variables can be found at the Collective Variables page.
To analyze the trajectory provided here, you should:
• Create a PLUMED input file with a text editor (let us call it plumed.dat) similar to the one above.
• Run the command plumed driver --mf_xtc traj.xtc --plumed plumed.dat.
Here traj.xtc is the trajectory that you want to analyze. Notice that driver can read multiple file formats using
embedded molfile plugins from VMD (that's where the mf letters come from).
Notice that you can also visualize trajectories with VMD directly. Trajectory traj.xtc can be visualized with the
command vmd ref.pdb traj-whole.xtc.
In the following we will make practice with computing and printing collective variables.
11.1.6.1
Exercise 1: Computing and printing collective variables
Analyze the traj-whole.xtc trajectory and produce a colvar file with the following collective variables.
• The gyration radius of the solute RNA molecule (GYRATION). Look in the ref.pdb file which are the atoms
that are part of RNA (search for the first occurrence of a water molecule, residue name SOL). Remember that
you don't need to list all the atoms: instead of ATOMS=1,2,3,4,5 you can write ATOMS=1-5.
• The torsional angle (TORSION) corresponding to the glycosidic chi angle χ of the first nucleotide. Since this
nucleotide is a purine (guanine), the proper atoms to compute the torsion are O4' C1 N9 C4. Find their serial
number in the ref.pdb file or learn how to select a special angle reading the MOLINFO documentation.
• The total number of contacts (COORDINATION) between all RNA atoms and all water oxygen atoms. For
COORDINATION, set reference distance R_0 to 2.5 A (be careful with units!!). Try to be smart in selecting
the water oxygen atoms without listing all of them explicitly.
• Same as before but against water hydrogen. Also in this case you should be smart to select water hydrogen
atoms. Documentation of GROUP might help.
• Distance between the Mg ion and the geometric center of the RNA duplex (use CENTER and DISTANCE).
Notice that some of the atom selections can be made in a easier manner by using the MOLINFO keyword with a
proper reference PDB file. Also read carefully the Groups and Virtual Atoms page before starting. Here you can
find a sample plumed.dat file that you can use as a template. Whenever you see an highlightedFILL string, this
is a string that you should replace.
Generated by Doxygen
678
Tutorials
BEGIN_PLUMED_FILE
# First load information about the molecule.
MOLINFO __FILL__
# Notice that this is special kind of "action" ("setup action")
# that is only used during setup. It will not be re-executed at each step.
# Define some group that will make the rest of the input more readable
# Here are the atoms belonging to RNA.
rna: GROUP ATOMS=1-258
# This is the Mg ion. A group with atom is also useful!
mg: GROUP ATOMS=6580
# This group should contain all the atoms belonging to water molecules.
wat: GROUP ATOMS=__FILL__
# Select water oxygens only:
owat: GROUP __FILL__
# Select water hydrogens only:
hwat: GROUP __FILL__
# Compute gyration radius:
r: GYRATION ATOMS=__FILL__
# Compute the Chi torsional angle:
c: TORSION ATOMS=__FILL__
# Compute coordination of RNA with water oxygens
co: COORDINATION GROUPA=rna GROUPB=owat R_0=__FILL__
# Compute coordination of RNA with water hydrogens
ch: COORDINATION GROUPA=rna GROUPB=hwat __FILL__
# Compute the geometric center of the RNA molecule:
ce: CENTER ATOMS=__FILL__
# Compute the distance between the Mg ion and the RNA center:
d: DISTANCE ATOMS=__FILL__
# Print the collective variables on COLVAR file
# No STRIDE means "print for every step"
PRINT ARG=r,c,co,ch,d FILE=COLVAR
Once your plumed.dat file is complete, you can use it with the following command
> plumed driver --plumed plumed.dat --mf_xtc whole.xtc
Scroll in your terminal to read the PLUMED log. As you can see, PLUMED gives a lot of feedback about the input
that he is reading. There's the place where you can check if PLUMED understood correctly your input.
The command above will create a file COLVAR like this one:
#! FIELDS time r c
#! SET min_c -pi
#! SET max_c pi
0.000000 0.788694
1.000000 0.804101
2.000000 0.788769
3.000000 0.790232
4.000000 0.796395
co ch d
-2.963150 207.795793 502.027244 0.595611
-2.717302 208.021688 499.792595 0.951945
-2.939333 208.347867 500.552127 1.014850
-2.940726 211.274315 514.749124 1.249502
3.050949 212.352810 507.892198 2.270682
Notice that the first line informs you about the content of each column and the second and third lines tell you that
variable c (the χ torsion) is defined between −π and +π .
In case you obtain different numbers, check your input, you might have made some mistake!
This file can then be shown with gnuplot
gnuplot> p "COLVAR" u 1:2, "" u 1:3
Generated by Doxygen
11.1 Trieste tutorial: Analyzing trajectories using PLUMED
679
As a final note, look at what happens if you run the exercise twice. The second time, PLUMED will back up the
previously produced file so as not to overwrite it. You can also concatenate your files by using the action RESTART
at the beginning of your input file.
In this first exercise we only computed simple functions of the atomic coordinates. PLUMED is very flexible and
allows you to also combine these functions to create more complicated variables. These variables can be useful
when you want to describe a complex conformational change. PLUMED implements a number of functions that can
be used to this aim that are described in the page Functions. Look at the following example:
BEGIN_PLUMED_FILE
# Distance between atoms 1 and 2:
d1: DISTANCE ATOMS=1,2
# Distance between atoms 1 and 3:
d2: DISTANCE ATOMS=1,3
# Distance between atoms 1 and 4:
d3: DISTANCE ATOMS=1,4
# Compute the sum of the squares of those three distances:
c: COMBINE ARG=d1,d2,d3 POWERS=2 PERIODIC=NO
# Sort the three distances:
s: SORT ARG=d1,d2,d3
# Notice that SORT creates a compund object with three components:
# s.1: the smallest distance
# s.2: the middle distance
# s.3: the largest distance
p: MATHEVAL ARG=d1,d2,d3 FUNC=x*y*z PERIODIC=NO
# Print the sum of the squares and the largest among the three distances:
PRINT FILE=COLVAR ARG=c,s.3
In case you have many distances to combine you can also use regular expressions to select them using ARG=(d.),
see Regular Expressions.
Notice for many functions you should say to PLUMED if the function is periodic. See Functions for a detailed
explanation of how to choose this keyword.
You might think that it is easier to combine the variables after you have written them already, using, e.g., an awk or
python script. That's fine if you are analyzing a trajectory. However, as we will learn later, computing variables within
PLUMED you will be able to add bias potentials on those combinations, influencing their dynamics. Actually, you
could implement any arbitrarily complex collective variable using just DISTANCE and MATHEVAL! Anyway, if the
CV combinations that you are willing to use can be computed easily with some external program, do it and compare
the results with the output of the PLUMED driver.
11.1.6.2
Exercise 1b: Combining collective variables
As an optional exercise, create a file with the following quantities:
• The sum of the distances between Mg and each of the phosphorous atoms.
• The distance between Mg and the closest phosphorous atom.
Notice that the serial numbers of the phosphorous atoms can be easily extracted using the following command
> grep ATOM ref.pdb | grep " P " | awk ’{print $2}’
Here's a template input file to be completed by you.
Generated by Doxygen
680
Tutorials
BEGIN_PLUMED_FILE
# First load information about the molecule.
MOLINFO __FILL__
# Define some group that will make the rest of the input more readable
mg: GROUP ATOMS=6580 # a group with one atom is also useful!
# Distances between Mg and phosphorous atoms:
d1: DISTANCE ATOMS=mg,33
d2: DISTANCE __FILL__
__FILL__
d6: DISTANCE __FILL__
# You can use serial numbers, but you might also use MOLINFO strings
# Compute the sum of these distances
c: COMBINE __FILL__
# Compute the distance between Mg and the closest phosphorous atom
s: SORT __FILL__
# Print the requested variables
PRINT FILE=COLVAR __FILL__
Notice that using the collective variable DISTANCES you might be able to do the same with a significantly simpler
input file! If you have time, also try that and compare the result.
The resulting COLVAR file should look like this one:
#! FIELDS
0.000000
1.000000
2.000000
3.000000
4.000000
11.1.7
time c s.1
6.655622 0.768704
7.264049 0.379416
7.876489 0.817820
8.230621 0.380191
13.708759 2.046935
Solving periodic-boundary conditions issues
While running PLUMED can also dump the coordinate of the internally stored atoms using DUMPATOMS. This
might seem useless (coordinates are already contained in the original trajectory) but can be used in the following
cases:
• To dump coordinates of virtual atoms that only exist within PLUMED (e.g. a CENTER).
• To dump snapshots of our molecule conditioned to some value of some collective variable (see UPDATE_IF).
• To dump coordinates of atoms that have been moved by PLUMED.
The last point is perhaps the most surprising one. Some of the PLUMED actions can indeed move the stored atoms
to positions better suitable for the calculation of collective variables.
The previous exercise was done on a trajectory where the RNA was already whole. For the next exercise you will
use the traj-broken.xtc file instead, which is a real trajectory produced by GROMACS. Open it with VMD to
understand what we mean with broken
> vmd ref.pdb traj-broken.xtc
Select Graphics, then Representations, then type nucleic in the box Selected Atoms. You will
see that your RNA duplex is not whole. This is not a problem during MD because of periodic boundary conditions.
However, it is difficult to analyze this trajectory. In addition, some collective variables that you might want to compute
could require the molecules to be whole (an example of such variables is RMSD).
You might think that there are alternative programs that can be used to reconstruct the molecules the molecules
that are broken by the periodic boundary correctly in your trajectory before analyzing it. However, you should keep
in mind that if you need to compute CVs on the fly to add a bias potential on those (as we will to in the next tutorials)
you will have to learn how to reconstruct the molecules that are broken by the periodic boundary within PLUMED. If
you know alternative tools that can reconstruct the molecules that are broken by the periodic boundary, it is a good
idea to also use them and compare the result with PLUMED.
Generated by Doxygen
11.1 Trieste tutorial: Analyzing trajectories using PLUMED
11.1.7.1
681
Exercise 2: Solving PBC issues and dump atomic coordinates
Analyze the provided trajectory traj-broken.xtc and use the DUMPATOMS action to produce new trajectories in gro format that contain:
• The RNA duplex made whole (not broken by periodic boundary conditions). You should read carefully the
documentation of WHOLEMOLECULES.
• The whole RNA duplex aligned to a provided template (structure reference.pdb). See FIT_TO_TEMPLATE,
using TYPE=OPTIMAL. Notice that you should provide to FIT_TO_TEMPLATE a pdb file with only the atoms
that you wish to align. Use the ref.pdb file as a starting point and remove the lines non containing RNA
atoms. More details on PDB files in PLUMED can be found here.
• The whole RNA duplex and Mg ion, but only including the snapshots where Mg is at a distance equal to at
most 4 A from phosphorous atom of residue 8. Search for the serial number of the proper phosphorous atom
in the PDB file and use the UPDATE_IF action to select the frames.
• The whole RNA duplex plus water molecules and mg ion wrapped around the center of the duplex. Compute
first the center of the duplex with CENTER then wrap the molecules with WRAPAROUND. Make sure that
individual water molecules are not broken after the move!
Here you can find a template input file to be completed by you.
BEGIN_PLUMED_FILE
# First load information about the molecule.
MOLINFO __FILL__
# Define here the groups that you need.
# Same as in the previous exercise.
rna: GROUP ATOMS=__FILL__
mg: GROUP ATOMS=__FILL__
wat: GROUP ATOMS=__FILL__
# Make RNA duplex whole.
WHOLEMOLECULES __FILL__
# Dump first trajectory in gro format.
# Notice that PLUMED understands the format based on the file extension
DUMPATOMS ATOMS=rna FILE=rna-whole.gro
# Align RNA duplex to a reference structure
# This should not be the ref.pdb file but a new file with only RNA atoms.
FIT_TO_TEMPLATE REFERENCE=__FILL__ TYPE=OPTIMAL
# Notice that before using FIT_TO_TEMPLATE we used WHOLEMOLECULES to make RNA whole
# This is necessary otherwise you would align a broken molecule!
# Dump the aligned RNA on a separate file
DUMPATOMS ATOMS=rna FILE=rna-aligned.gro
# Compute the distance between the Mg and the Phosphorous from residue 8
d: DISTANCE ATOMS=mg,__FILL__ ## put the serial number of the correct phosphorous here
# here we
UPDATE_IF
DUMPATOMS
UPDATE_IF
only dump frames conditioned to the value of d
ARG=d __FILL__
ATOMS=rna,mg FILE=rna-select.gro
ARG=d __FILL__ # this command is required to close the UPDATE_IF above
# compute the center of the RNA molecule
center: CENTER ATOMS=rna
# Wrap atoms correctly
WRAPAROUND ATOMS=mg AROUND=__FILL__
WRAPAROUND ATOMS=wat AROUND=center __FILL__ # anything missing here?
# Dump the last trajectory
DUMPATOMS ATOMS=rna,wat,mg FILE=rna-wrap.gro
Generated by Doxygen
682
Tutorials
After you have prepared a proper plumed.dat file, you can use it with the following command
> plumed driver --plumed plumed.dat --mf_xtc broken.xtc
Visualize the resulting trajectories using VMD. Since the gro files already contain atom names, you do not need to
load the pdb file first. For instance, the first trajectory can be shown with
> vmd rna-whole.gro
TODO: I should perhaps add reference plots
If you just simulate a single solute molecule in water it is easy to understand how to pick the right options for
WHOLEMOLECULES. However, if you have multiple molecules it can be rather tricky. In the example above, we
used WHOLEMOLECULES on the RNA molecule which is actually a duplex, that is two separated chains. This was
correct for the following reasons:
• the two chains are kept together by hydrogen bonds, and
• the last atom of the first chain is always close to the first atom of the second chain.
In case the two molecules can separate from each other this would be rather problematic.
We will now see what happens when using WHOLEMOLECULES on multiple molecules incorrectly.
11.1.7.2
Exercise 2b: Mistakes with WHOLEMOLECULES
Prepare a PLUMED input file that makes all the water molecules whole. Use the following template
BEGIN_PLUMED_FILE
# First load information about the molecule.
MOLINFO __FILL__
# Define here the groups that you need
rna: GROUP ATOMS=__FILL__
mg: GROUP ATOMS=__FILL__
wat: GROUP ATOMS=__FILL__
# Make RNA whole
WHOLEMOLECULES ENTITY0=rna
# Now make water whole as if it was a single molecule
WHOLEMOLECULES ENTITY0=wat
# And dump the resulting trajectory
DUMPATOMS ATOMS=rna,wat,mg FILE=wrong.gro
Now look at the resulting file with vmd wrong.gro. Can you understand which is the problem?
The important take-home message here is that when you want to reconstruct periodic boundary conditions correctly
in systems with multiple molecules you should be careful and always verify with DUMPATOMS that the system is
doing what you expect.
In an exercise above we used FIT_TO_TEMPLATE. This action uses as a reference a PDB file which typically
contains a subset of atoms (those that are fitted). However, when you apply FIT_TO_TEMPLATE with TYPE=O←PTIMAL, the whole system is translated and rotated. The whole system here means all atoms plus the vectors
defining the periodic box.
Generated by Doxygen
11.1 Trieste tutorial: Analyzing trajectories using PLUMED
11.1.7.3
683
Exercise 2c: Mastering FIT_TO_TEMPLATE
Check how the periodic box rotates when using FIT_TO_TEMPLATE. Use the following template
BEGIN_PLUMED_FILE
# First load information about the molecule.
MOLINFO __FILL__
# Define here the groups that you need
rna: GROUP ATOMS=__FILL__
mg: GROUP ATOMS=__FILL__
wat: GROUP ATOMS=__FILL__
# Make RNA whole
WHOLEMOLECULES ENTITY0=rna
# Here’s a compund variable with the box vectors
# computed before aligning RNA
cell_before: CELL
# Now we align RNA
FIT_TO_TEMPLATE __FILL__ TYPE=OPTIMAL
# Here’s a compund variable with the box vectors
# computed after aligning RNA
cell_after: CELL
PRINT ARG=cell_before.* FILE=CELL_BEFORE
PRINT ARG=cell_after.* FILE=CELL_AFTER
You should obtains files like the ones reported below.
CELL_BEFORE should be
#! FIELDS
0.000000
1.000000
2.000000
3.000000
4.000000
time cell_before.ax cell_before.ay cell_before.az cell_before.bx cell_before.by cell_before.bz cell_
4.533710 0.000000 0.000000 0.000000 4.533710 0.000000 2.266860 2.266860 3.205821
4.533710 0.000000 0.000000 0.000000 4.533710 0.000000 2.266860 2.266860 3.205821
4.533710 0.000000 0.000000 0.000000 4.533710 0.000000 2.266860 2.266860 3.205821
4.533710 0.000000 0.000000 0.000000 4.533710 0.000000 2.266860 2.266860 3.205821
4.533710 0.000000 0.000000 0.000000 4.533710 0.000000 2.266860 2.266860 3.205821
CELL_AFTER should be
#! FIELDS
0.000000
1.000000
2.000000
3.000000
4.000000
time cell_after.ax
4.533710 -0.000059
-0.396226 4.289476
-3.016552 1.123968
-4.083873 1.923282
-4.020722 2.094622
cell_after.ay cell_after.az cell_after.bx cell_after.by cell_after.bz cell_after.
-0.000008 0.000059 4.533710 -0.000172 2.266895 2.266952 3.205730
-1.413481 -1.244340 1.260309 4.173460 2.249665 3.307132 2.134590
-3.192434 -1.055123 -4.375593 -0.543533 -4.309790 -1.356178 0.375612
-0.421306 0.339577 -0.267554 -4.513051 -3.243502 -2.069026 -2.398628
-0.029688 -1.060483 -1.979827 3.938298 -1.263169 2.532008 3.542306
As you can see, the generating vectors of the periodic lattice before fitting are constant. On the other hand, after
fitting these vectors change so as to keep RNA correctly aligned to its reference structure.
Later on you will learn how to add a bias potential on a give collective variable. In principle, you could also add a
RESTRAINT to the cell_after.∗ variables of the last example. This would allow you to force your molecule to
a specific orientation.
Generated by Doxygen
684
Tutorials
11.1.7.4
Conclusions
In summary, in this tutorial you should have learned how to use PLUMED to:
• Manipulate atomic coordinates.
• Compute collective variables.
All of this was done by just reading an already available trajectory. Notice that there are many alternative tools that
could have been used to do the same exercise. Indeed, if you are familiar with other tools, it might be a good idea
to also try them and compare the results. The special things of working with PLUMED are the following:
• PLUMED implements a vast library of useful collective variables. Browse the manual and search for ideas
that are suitable for your system.
• PLUMED has a simple and intuitive syntax to combine collective variables ending up in descriptors capable
to characterize complex conformational changes.
• And finally, the most special thing: any collective variable that can be computed within PLUMED can also be
biased while you are running your MD simulation! You will learn more later about this topic.
The last point is probably the main reason why PLUMED exists and what distinguishes it from other available
software.
11.2
Trieste tutorial: Averaging, histograms and block analysis
11.2.1
Introduction
The aim of this tutorial is for you to understand how we analyze trajectory data by calculating ensemble averages.
One key point we try to make in this tutorial is that you must always calculate averaged quantities from our
simulation trajectories. Consequently, in order to understand the analysis that is done when we perform molecular
dynamics and Monte Carlo simulations, we will need to understand some things about probability and statistics. In
fact, the things that we need to understand about probability and statistics are going to be the main subject of this
tutorial. Therefore, in order to make our lives easier, we are not going to work with simulation trajectories in this
tutorial. We are going to use model data instead.
11.2.2
Objectives
Once this tutorial is completed students will:
• Be able to explain the role played by the central limit theorem in many of the analysis methods that we perform
on simulation trajectories.
• Be able to use PLUMED to calculate ensemble averages and histograms using the keywords AVERAGE and
HISTOGRAM.
• Be able to use PLUMED to perform block analysis of trajectory data using the keywords AVERAGE and
HISTOGRAM.
• Be able to use PLUMED to calculate unbiased ensemble averages and histograms from biased trajectories
by using the keywords AVERAGE, HISTOGRAM and REWEIGHT_BIAS.
• Be able to explain how block analysis can be used to detect problems with error bar underestimation in
correlated data.
Generated by Doxygen
11.2 Trieste tutorial: Averaging, histograms and block analysis
11.2.3
685
Background
Let's begin by thinking about what is actually output by a simulation trajectory. You probably know by now that
molecular dynamics gives us a trajectory that provides us with information on how the positions and velocities
of the all the atoms in the system change with time. Furthermore, you should by now understand that we can
use PLUMED to reduce the amount of information contained in each of the trajectory frames to a single number or a low-dimensional vector by calculating a collective variable or a set of collective variables. As we saw in
Trieste tutorial: Analyzing trajectories using PLUMED this process of lowering the dimensionality of the data contained in a simulation trajectory was vital as we understand very little by watching the motions of the hundreds of
atoms that the system we are simulating contains. If we monitor the appropriate key variables, however, we can
determine whether a chemical reaction has taken place, whether the system has undergone a phase transition to a
more ordered form or if a protein has folded. Even so if all we do is monitor the values the the collective variables
take during the simulation our result can only ever be qualitative and we can only say that we observed this process
to take place under these particular conditions on one particular occasion. Obviously, we would like to be able to do
more - we would like to be able to make quantitative predictions based on the outcomes of our simulations.
The first step in moving towards making these quantitative predictions involves rethinking what precisely our simulation trajectory has provided us with. We know from rudimentary statistical mechanics that when we perform a
molecular dynamics simulation in the NVT ensemble the values of the collective variables that we obtain for each of
our trajectory frames, X , are samples from the following probability distribution:
0
R
P (s ) =
dxdpδ(s(x) − s0 )e−
R
dxdpe−
H(x,p)
kB T
H(x,p)
kB T
In this expression the integral signs are used to represent 6N -dimensional integrals that run over all the possible
positions and momenta that the N atoms in our system can take. H(x, p) is the Hamiltonian and kB and T are
Boltzmann's constant and the temperature respectively. The quantity calculated by this quotient is the probability
that our CV will take a value s0 . The quantity in the denominator of the above expression is the canonical partition
function while the δ function in the integral in the numerator ensures that only those configurations that have a CV
value, s(x), equal to s0 contribute to the integral in the numerator.
The fact that we know what distribution the X -values obtained from our trajectory frames are taken from is not
particularly helpful as it is impossible to calculate the integrals in the expression above analytically. The fact that we
know that our trajectory frames represent samples from a distribution is helpful, however, because of a result know
as the Central Limit Theorem. This theorem states the following:
Sn
n
lim P q
n→∞
− hY i
h(δY )2 i
n
≤ z = Φ(z)
In this expression Φ(z) is the cumulative probability distribution function for a standard normal distribution and Sn
is a sum of n independent samples from a probability distribution - in our case the probability distribution that we
introduced in the previous equation. i is the ensemble average for the quantity Y (x), which, in our case, we can
calculate as follows:
R
hY i =
dxdpY (x)e−
R
dxdpe−
H(x,p)
kB T
H(x,p)
kB T
Lastly, the quantity h(δY )2 i is a measure of the extent of the fluctuations we will observe in the Y values that we
samples. This quantity is calculated using:
h(δY )2 i = hY 2 i − hY i2
The statement of the theorem provided above is compact way of stating the formal theorem. This is undoubtedly
pleasing to mathematicians but to understand why this idea is so important in the context of molecular simulation
it is useful to think about this in a slightly less formal way. The central limit theorem essentially tells us that if we
Generated by Doxygen
686
Tutorials
take the set of random variables we extract from a simulation trajectory, which we know represent samples from the
complicated distribution in the first equation above, and we add all these random variables together and divide by n
we can think of the final number we obtain as a random variable that is taken from a Gaussian distribution. In other
words, the probability density function for the sample mean, Snn , that we get from our trajectory frames is given by:
P (Sn ) = q
1
2πh(δY )2 i
n
exp −
Sn
n − hY i
2
2 h(δYn ) i
!
This function is shown plotted for various values of n in the movie at https://www.youtube.←com/watch?v=-7hlP-2dG_o&feature=youtu.be.
You can see clearly that this distribution becomes more strongly peaked around hY i (which I set equal to 0 in the
movie) as n increases.
This observation is important as it ensures that the probability that Snn lies close to the true value of the expectation
value of our distribution, hY i, increases as we increase the value of n. The central limit theorem therefore allows
us to get an estimate for the ensemble average for a particular quantity Y by taking repeated samples of Y
from our distribution. These samples can be taken by, for example, performing a molecular dynamics simulation.
Furthermore, and as we will see in the exercises that follow, we can also get an estimate of how much we might
expect the system to fluctuate about this average. Incidentally, if you are confused at this stage you might want to
work through these two videos and exercises in order to get a better understanding of the central limit theorem,
confidence limits and error bars:
• Error bars exercise: http://gtribello.github.io/mathNET/error_bar_video.html
• Confidence limits exercise: http://gtribello.github.io/mathNET/central-limit-theorem-video.←-
html
11.2.4
Instructions
11.2.4.1
Calculating an ensemble average
As discussed in the introduction we are going to be using model data in this exercise so we must begin by generating
some model data to analyze using PLUMED. The following short python script will generate 10000 (pseudo) random
variables between 0 and 1 from a uniform distribution in a format that PLUMED can understand:
import random
print("#! FIELDS time rand")
for i in range(0,10001):
print(i, random.uniform(0,1) )
Copy the contents of the box above to a plain text file called generate_data.py, save the file and then execute the
script within it by running:
> python generate_data.py > my_data
This will generate a file called my_data that contains 10001 uniform random variables. PLUMED will ignore the first
number in the colvar file as it assumes this is the initial configuration you provided for the trajectory. The sample
mean will thus be calculated from 10000 random variables. Plot this data now using gnuplot and the command:
gnuplot> p ’my_data’ u 1:2 w p
Generated by Doxygen
11.2 Trieste tutorial: Averaging, histograms and block analysis
687
The probability distribution that we generated these random variables is considerably simpler than the probability
distribution that we would typically sample from during an MD simulation. Consequently, we can calculate the exact
values for the ensemble average and the fluctuations for this distribution. These are:
Z
hXi =
0
1
xd x =
x2
2
1
=
0
1 2
hX i =
2
Z
1
0
x2 d x =
x3
3
1
=
0
1
1
h(δX)2 i = hX 2 i − hXi2 =
3
12
Lets now try estimating these quantities by calculating Snn from the points we generated and exploiting the central
limit theorem. We can do this calculation by writing a PLUMED input file that reads:
BEGIN_PLUMED_FILE
data: READ FILE=my_data VALUES=rand
d2: MATHEVAL ARG=data VAR=a FUNC=a*a PERIODIC=NO
av: AVERAGE ARG=data STRIDE=1
av2: AVERAGE ARG=d2 STRIDE=1
PRINT ARG=av,av2 STRIDE=10000 FILE=colvar
If you copy this input to a file called plumed.dat you can then run the calculation by executing:
> plumed driver --noatoms
When the calculation is finished you should have a file called colvar that contains the estimate of the ensemble
averages hXi and hX 2 i. To be clear, the quantities output in this file are:
hXi =
N
1 X
Xi
N i=1
and
hX 2 i
N
1 X 2
X
N i=1 i
We can calculate the fluctuations, (δX)2 , from them using:
(δX)2 = hX 2 i − hXi2
We can then compare the values that we got for these estimated values with those that we got for the true values.
You should find that the agreement is reasonable but not perfect.
11.2.4.2
Calculating a histogram
We can use what we have learned about calculating an ensemble average to calculate an estimate for the probability density function or probability mass function for our random variable. The theory behind what we do here is
explained in this video http://gtribello.github.io/mathNET/histogram-video.html
To do such a calculation with PLUMED on the random variables we generated from the uniform distribution in the
previous section we would use an input like the one below:
BEGIN_PLUMED_FILE
data: READ FILE=my_data VALUES=rand
hh: HISTOGRAM ARG=data STRIDE=1 GRID_MIN=0 GRID_MAX=1.0 GRID_BIN=20 KERNEL=DISCRETE
DUMPGRID GRID=hh FILE=my_histogram.dat
Once again you can run this calculation by using the command:
> plumed driver --noatoms
Once this calculation is completed you can then plot the output using gnuplot and the command:
gnuplot> p ’my_histogram.dat’ u 1:2 w l
In the previous section we compared the estimates we got for the ensemble average with the exact analytical values,
which we could determine because we know that the data was sampled from a uniform distribution between 0 and
1. We can do a similar thing with the histogram. Can you determine what the true (analytic) values for the
probabilities in the histogram above should be?
Also notice that the probability estimate for the first and last points in our histogram are lower than the probability
estimates for the other points.
Can you determine why these two points have a lower probability?
Generated by Doxygen
688
11.2.4.3
Tutorials
Problem I: Making the best use of the data
As discussed in previous sections the sample mean of the CV values from our trajectory frames is a random variable
and the central limit theorem tells us something about the the distribution from which this random variable is drawn.
The fact that we know what distribution the sample mean is drawn from is what allows us to estimate the ensemble
average and the fluctuations. The fact that this recipe is only estimating the ensemble average is critical and this
realization should always be at the forefront of our minds whenever we analyze our simulation data. The point, once
again, is that the sample mean for CV values from the simulation is random. As is explained in this video http←://gtribello.github.io/mathNET/central-limit-theorem-video.html, however, we can
use the central limit theorem to calculate a range, {hXi − , hXi + }, that the sample mean for the CV values, Snn ,
will fall into with a probability pc using:
r
=
h(δX)2 i −1
Φ
n
pc + 1
2
Here Φ−1 is the inverse of the cumulative probability distribution function for a normal distribution with mean 0 and
variance 1. As you can see this range gets smaller as the number of samples from which you calculate the mean, n,
increases. As is shown in the figure below, however, the rate at which this range narrows in size is relatively small.
This graph hopefully illustrates to you that an estimate of the ensemble average that is taken over 500 trajectory
frames is not guaranteed to lie significantly closer to the true ensemble average than an estimate taken from 100
trajectory frames. For this reason, we might choose to split the data into blocks that all have equal length. Will will
then estimate the average for each of these blocks separately. As we will see in the remainder of this exercise this
process of block averaging has a number of other advantages. For now though we are just going to use it to test
that the results from the various parts of ``the trajectory" are all consistent.
We can perform a block averaging on the data we generated at the start of the first exercise above by using PLUMED
and the input file below:
BEGIN_PLUMED_FILE
data: READ FILE=my_data VALUES=rand
av: AVERAGE ARG=data STRIDE=1 CLEAR=1000
PRINT ARG=av STRIDE=1000 FILE=colvar
Once again this calculation can be executed by running the command:
> plumed driver --noatoms
The key differences between this input and the ones that we have seen previously is the CLEAR keyword on the
line AVERAGE. The instruction CLEAR=1000 tells PLUMED that the data that has been accumulated for averaging
should be reset to zero (cleared) every 1000 steps. If you look at the subsequent PRINT command in the above
input you see the instruction STRIDE=1000. The above input thus accumulates an average over 1000 trajectory
frames. This average is then output to the file colvar on step 1000 and the accumulated data is immediately cleared
after printing so that a new average over the next 1000 steps can be accumulated. We can plot the averages that
were output from the calculation above by using gnuplot and the following command:
gnuplot> p ’colvar’ u 1:2 w l
If you try this now you should see that all the average values that were calculated are relatively consistent but
that there are differences between them. Try to calculate the size of for a 90 % confidence limit around
this random variable using the formula that was provided above. How many of the averages that you
extracted using PLUMED lie within this range? Is this behavior inline with your expectations based on your
understanding of what a confidence limit is?
We can also perform block averaging when we estimate histograms using PLUMED. The following input will calculate
these block averaged histograms for the data we generated at the start of this exercise using PLUMED.
Generated by Doxygen
11.2 Trieste tutorial: Averaging, histograms and block analysis
689
BEGIN_PLUMED_FILE
data: READ FILE=my_data VALUES=rand
hh: HISTOGRAM ARG=data STRIDE=1 GRID_MIN=0 GRID_MAX=1.0 GRID_BIN=20 KERNEL=DISCRETE CLEAR=1000
DUMPGRID GRID=hh FILE=my_histogram.dat STRIDE=1000
Notice that the input here has the same structure as the input for the AVERAGE. Once again we have a CLE←AR=1000 keyword that tells PLUMED that the data that has been accumulated for calculating the histogram should
be deleted every 1000 steps. In addition, we can set a STRIDE for DUMPGRID and thus output the histogram from
each of these blocks of trajectory data separately. The difference between the output from this input and the output
from the input above is that in this case we have multiple output files. In particular, the input above should give you
10 output files which will be called:
• analysis.0.my_histogram.dat = analysis of data in first 1000 frames
• analysis.1.my_histogram.dat = analysis of data in second 1000 frames
• analysis.2.my_histogram.dat = analysis of data in third 1000 frames
• analysis.3.my_histogram.dat = analysis of data in fourth 1000 frames
• analysis.4.my_histogram.dat = analysis of data in fifth 1000 frames
• analysis.5.my_histogram.dat = analysis of data in sixth 1000 frames
• analysis.6.my_histogram.dat = analysis of data in seventh 1000 frames
• analysis.7.my_histogram.dat = analysis of data in eighth 1000 frames
• analysis.8.my_histogram.dat = analysis of data in ninth 1000 frames
• my_histogram.dat = analysis of data in tenth 1000 frames
We can plot all of these histograms using gnuplot and the command:
gnuplot> p ’analysis.0.my_histogram.dat’ u 1:2 w l, ’analysis.1.my_histogram.dat’ u 1:2 w l, ’analysis.2.my_hi
Performing a comparison between the results from each of these blocks of data is more involved than the analysis we
performed when comparing the ensemble averages as we have more data. The essential idea is the same, however,
and, if you have time at the end of the session, you might like to see if you can write a script that determines what
fraction of the many averages we have calculated here lie within the confidence limits.
11.2.4.4
Problem II: Dealing with rare events and simulation biases
As is discussed in many of the tutorials that are provided here one of the primary purposes of PLUMED is to use
simulation biases to resolve the rare events problem. When we use these technique we modify the Hamiltonian,
H(x, p), and add to it some bias, V (x). The modified Hamiltonian thus becomes:
H 0 (x, p) = H(x, p) + V (x)
and as such the values of the collective variables that we obtain from each of our trajectory frames are samples
from the following distribution:
P (s0 ) =
R
dxdpδ(s(x) − s0 )e−
R
−
dxdpe−
e
H(x,p)
kB T
H(x,p)
kB T
e
V (x)
BT
−k
V (x)
kB T
Using a bias in this way is enormously helpful as we can ensure that we sample from a particular part of configuration
space. We appear to have sacrificed, however, the ability to extract estimates of ensemble averages for the unbiased
Generated by Doxygen
690
Tutorials
distribution using the central limit theorem. If we calculate the mean from a set of trajectory frames that are sampled
from the distribution above we will get an estimate for the ensemble average in this biased distribution. As we will
see in this exercise, however, this is not really a problem as we can use reweighting techniques to extract ensemble
averages for the unbiased distribution.
Lets begin by generating some new trajectory data. The following python script generates a set of random variables
from a (truncated) normal distribution with σ = 0.5 and µ = 0.6. In other words, points are generated from the
following probability distribution but if they don't fall in a range between 0 and 1 they are discarded:
P (x) = √
(x − µ)2
1
exp −
2σ 2
2πσ
import random
n = 0
print("#! FIELDS time rand")
while True :
x = random.gauss( 0.6, 0.1732 )
if (x>=0) & (x<=1) :
print(n, x )
n = n + 1
if n==10001 : break
Copy the script above to a file called gen-normal.py and then execute the python script within it using the command:
> python gen-normal.py > mynormal
Use what you have learned from the exercises above to estimate the ensemble average from these generated data points using PLUMED. If you want you can use block averaging but it does not matter if you do
it by just considering all the data in the input file. What would you expect the ensemble average to be and
how does the estimate you get from PLUMED compare with the true value?
You should have found that the ensemble average that you get when you perform the experiment described in
the previous paragraph is different from the ensemble average that you get when you considered the uniform
distribution. This makes sense as the distribution we sampled from here is approximately:
x − 0.6
1
√ exp −
P (x) =
2(0.03)2
0.03 ∗ 2π
This is different from the distribution we sampled from in the previous exercises. A question we might therefore
ask is: can we extract the ensemble average for the uniform distribution that we sampled in previous exercises
by sampling from this different distribution? In the context of the experiment we are performing here with the
random variables this question perhaps feels somewhat absurd and pointless. In the context of molecular simulation,
however, answering this question is essential as our ability to extract the true, unbiased distribution from a simulation
run with a bias relies on being able to perform this sort of reweighting.
The true value of the ensemble average, which we estimated when we analyzed the data generated from the
Gaussian using the python script above is given by:
xe−V (x) dx
hXi = R0 1
e−V (x) dx
0
R1
where
V (x) =
(x − x)2
2σ 2
By contrast the ensemble average in the exercises involving the uniform distribution is given by:
Generated by Doxygen
11.2 Trieste tutorial: Averaging, histograms and block analysis
R1
0
y dy
hY i = R 1
0
691
ye−V (y) e+V (y) dy
= R0 1
dy
e−V (y) e+V (y) dy
0
R1
We can use the final expression here to reweight the data that we sampled from the Gaussian. By doing so can
thus extract ensemble averages for the uniform distribution. The trick here is calculate the following weighted mean
rather than the unweighted mean that we calculated previously:
P
Yi e+V (Yi )
hY i ≈ Pi +V (Y )
i
ie
where here the sums run over all the random variables, the Yi s, that we sampled from the Gaussian distribution. If
you used the script above the V (Yi ) values were output for you so you can calculate this estimate of the ensemble
average for the unbiased distribution in this case using the following PLUMED input.
BEGIN_PLUMED_FILE
UNITS NATURAL #This ensures that Boltzmann’s constant is one
data: READ FILE=mynormal VALUES=rand IGNORE_FORCES
mm: RESTRAINT ARG=data AT=0.6 KAPPA=33.333
rw: REWEIGHT_BIAS TEMP=1
av: AVERAGE ARG=data STRIDE=1 LOGWEIGHTS=rw
PRINT ARG=av STRIDE=10000 FILE=colvar
Try to run this calculation now using:
> plumed driver --noatoms
and see how close you get to the ensemble average for the uniform distribution. Once you have done this try the
following input, which allows you to compute the reweighted histogram.
BEGIN_PLUMED_FILE
UNITS NATURAL #This ensures that Boltzmann’s constant is one
data: READ FILE=mynormal VALUES=rand IGNORE_FORCES
mm: RESTRAINT ARG=data AT=0.6 KAPPA=33.333
rw: REWEIGHT_BIAS TEMP=1
hh: HISTOGRAM ARG=data STRIDE=1 GRID_MIN=0 GRID_MAX=1.0 GRID_BIN=20 KERNEL=DISCRETE LOGWEIGHTS=rw
DUMPGRID GRID=hh FILE=my_histogram.dat
Plot the histogram that you obtain from this calculation using the command:
gnuplot> p ’my_histogram.dat’ w l
Now suppose that the data we generated for this exercise had come from an MD simulation. What would the
unbiased Hamiltonian in this MD simulation have looked like and what functional form would our simulation
bias have taken?
Generated by Doxygen
692
11.2.4.5
Tutorials
Problem III: Dealing with correlated variables
As a good scientist you have probably noticed that we have failed to provide error bars around our estimates for
the ensemble average in previous sections. Furthermore, you may have found that rather odd given that I showed
you how to estimate the variance in the data in the very first exercise. This ignoring of the error bars has been
deliberate, however, as there is a further problem with the data that comes from molecular dynamics trajectories
that we have to learn to deal with and that will affect our ability to estimate the error bars. This problem is connected
to the fact that the central limit theorem only holds when we take a sum of uncorrelated and identical random variables. Random variables that are generated from simulation trajectories will contain correlations simply
because the system will most likely not diffuse from one edge of CV space to the other during a single timestep. In
other words, the random CV value that we calculate from the (i + 1)th frame of the trajectory will be similar to the
value obtained from the ith trajectory frame. This problem can be resolved, however, and to show how we will thus
use the following python script to generate some correlated model data:
import random
prev = 0.;
print("#! FIELDS time rand")
for i in range(0,10001):
new = 0.95*prev + 2*random.uniform(0,1) - 1
print( i, new/2. + 0.5 )
prev = new
Copy the python script above to a filled called correlated-data.py and then execute the script using the command:
> python correlated-data.py > mycorr
The autocorrelation function, R(τ ) provides a simple method for determining whether or not there are correlations
between the random variables, X , in our time series. This function is defined as follows:
R(τ ) =
h(Xt − hXi)(Xt+τ − hXi)i
h(δX)2 i
At present it is not possible to calculate this function using PLUMED. If we were to do so for the samples taken from
the uniform distribution and the correlated samples that were taken from the distribution the python script above
we would find that the auto correlation functions for these random variables look something like the figures shown
below:
To understand what these functions are telling us lets deal with the samples from the uniform distribution first. The
autocorrelation function in this case has a value of 1 when τ is equal to 0 and a value of 0 in all other cases. This
function thus tells us that each random variable is perfectly correlated with itself but that there are no correlations
between the distributions we sampled adjacent variables from. In other words, each of the random variables we
generate are independent. If we now look at the autocorrelation function for the distribution that is sampled by the
python script above we see that the autocorrelation function slowly decays to zero. There are, therefore, correlations
between the random variables that we generate that we must account for when we perform our analysis.
We account for the correlations in the data when we do our analysis by performing a block analysis. To understand
what precisely this involves we are going to perform the analysis with PLUMED and explain the results that we
get at each stage of the process. We will begin by analyzing the data we generated by sampling from the uniform
distribution using the following PLUMED input:
Generated by Doxygen
11.2 Trieste tutorial: Averaging, histograms and block analysis
693
BEGIN_PLUMED_FILE
data: READ FILE=my_data VALUES=rand
av5: AVERAGE ARG=data STRIDE=1 CLEAR=5
PRINT ARG=av5 FILE=colvar5 STRIDE=5
av10: AVERAGE ARG=data STRIDE=1 CLEAR=10
PRINT ARG=av10 FILE=colvar10 STRIDE=10
av15: AVERAGE ARG=data STRIDE=1 CLEAR=15
PRINT ARG=av15 FILE=colvar15 STRIDE=15
av20: AVERAGE ARG=data STRIDE=1 CLEAR=20
PRINT ARG=av20 FILE=colvar20 STRIDE=20
av25: AVERAGE ARG=data STRIDE=1 CLEAR=25
PRINT ARG=av25 FILE=colvar25 STRIDE=25
av30: AVERAGE ARG=data STRIDE=1 CLEAR=30
PRINT ARG=av30 FILE=colvar30 STRIDE=30
av35: AVERAGE ARG=data STRIDE=1 CLEAR=35
PRINT ARG=av35 FILE=colvar35 STRIDE=35
av40: AVERAGE ARG=data STRIDE=1 CLEAR=40
PRINT ARG=av40 FILE=colvar40 STRIDE=40
av45: AVERAGE ARG=data STRIDE=1 CLEAR=45
PRINT ARG=av45 FILE=colvar45 STRIDE=45
av50: AVERAGE ARG=data STRIDE=1 CLEAR=50
PRINT ARG=av50 FILE=colvar50 STRIDE=50
av55: AVERAGE ARG=data STRIDE=1 CLEAR=55
PRINT ARG=av55 FILE=colvar55 STRIDE=55
av60: AVERAGE ARG=data STRIDE=1 CLEAR=60
PRINT ARG=av60 FILE=colvar60 STRIDE=60
av65: AVERAGE ARG=data STRIDE=1 CLEAR=65
PRINT ARG=av65 FILE=colvar65 STRIDE=65
av70: AVERAGE ARG=data STRIDE=1 CLEAR=70
PRINT ARG=av70 FILE=colvar70 STRIDE=70
Copy the input above to a file called plumed.dat and run the calculation using the command:
> plumed driver --noatoms
This calculation should output 14 colvar files, which should then be further analyzed using the following python
script:
import numpy as np
import math
for i in range(1,15):
#Read in each colvar file
fmult = 5*i
dat = np.loadtxt( ’colvar’ + str(fmult) )
# Compute the square of all the average values in the colvar
sq = dat[1:,1]**2
# Now compute the average over all the averages
mean = np.sum( dat[1:,1] ) / len( dat[1:,1] )
#Compute the average of the squares of the individual averages
mean2 = np.sum( sq ) / len( sq )
#Compute the population variance amongst the block averages
population_variance = mean2 - mean*mean
#Convert the population variance into a sample variance by multiplying by the bessel factor
sample_variance = ( len( sq ) / ( len(sq) - 1 ) )*population_variance
# Print out the length of the blocks, the final average taken over all blocks and the square
# root of the sample variance divided by the number of data points that this estimate was
# calcualted from. This last term is a measure of the eror bar
print( fmult, mean, math.sqrt( sample_variance / len(sq) ) )
Copy this script to a file called block-average-script.py and then execute the contents using the command:
> python block-average-script.py > my_averages.dat
This will output a single file called my_averages.dat that can be plotted using gnuplot and the command:
Generated by Doxygen
694
Tutorials
gnuplot> p ’my_averages.dat’ u 1:2:3 w e, ’my_averages.dat’ w l
The final result should be a graph like that shown in the left panel of the figure below. The figure on the right shows
what you should obtain when you repeat the same analysis on the correlated data that we generated using the
python script in this section.
The output that you obtain from these two calculations is explained in the video at: http←://gtribello.github.io/mathNET/block_averaging_video.html Before watching this explanation though take some time to note down the differences between the two graphs above. Try to look
through the scripts above and to understand what is being done in the PLUMED inputs and the python
scripts above so as to work out what the data in these two figures are telling you.
11.2.4.6
Putting it all together
In this final exercise we are going to try to combine everything we have seen in the previous sections. We are going
to sample from the distribution that was introduced in Problem II: Dealing with rare events and simulation biases.
This time though we are not going to generate random variables from the Gaussian directly. We are instead going
to use Monte Carlo sampling. This sampling method is going to give us correlated data so we will need to use ideas
from Problem III: Dealing with correlated variables in order to get a proper estimate of the error bars. Furthermore,
we are not going to try to extract ensemble averages that tell us about the distribution we sampled from. Instead we
are going to reweight using the ideas from Problem II: Dealing with rare events and simulation biases and extract
the unbiased distribution.
The first step in doing all this is, as always, to generate some data. The python script below will generate this data:
import math
import random
# Energy given by a harmonic potential centered at 0.6
#This ensures that our data represent samples from a Gaussian with
# mean 0.6 and variance 0.1732
def calc_eng( x ) :
return 0.5*33.333*pow((x-0.6),2)
x = 0.5
eng = calc_eng( x )
print("#! FIELDS time rand")
for i in range(0,100010):
# Generate new random position from old position
newx = x + 0.1*random.uniform(0,1) - 0.05
#Apply periodic boundary conditions
if( newx > 1.0 ) : newx = newx - 1.0
if( newx < 0.0 ) : newx = newx + 1.0
#Monte Carlo criterion
new_eng = calc_eng( newx )
if( new_eng python do-monte-carlo.py > mcdata
This will run a short Monte Carlo simulation that generates (time-correlated) random data from a (roughly) Gaussian distribution by attempting random translational moves of up to 0.1 units. An autocorrelation function that was
calculated using data generated using this script is shown below. You can clearly see from this figure that there are
correlations between the adjacent data points in the time series and that we have to do block averaging as a result.
We can use the following PLUMED input to calculate block averages for the unbiased histogram from the data we
generated:
Generated by Doxygen
11.2 Trieste tutorial: Averaging, histograms and block analysis
695
BEGIN_PLUMED_FILE
UNITS NATURAL #This ensures that Boltzmann’s constant is one
data: READ FILE=mcdata VALUES=rand IGNORE_FORCES
mm: RESTRAINT ARG=data AT=0.6 KAPPA=33.333
rw: REWEIGHT_BIAS TEMP=1
hh: HISTOGRAM ARG=data STRIDE=1 GRID_MIN=0 GRID_MAX=1.0 GRID_BIN=20 KERNEL=DISCRETE LOGWEIGHTS=rw CLEAR=500
DUMPGRID GRID=hh FILE=my_histogram.dat STRIDE=500
Notice that this input instructs PLUMED to calculate block averages for the histogram from each set of 500 consecutive frames in the trajectory.
I have worked out that this is an appropriate length of time to average over by performing the analysis described in
Problem III: Dealing with correlated variables.
We will come back to how precisely I did this momentarily, however. For the time being though you can execute this
input using:
> plumed driver --noatoms
Executing this command will generate a number of files containing histograms. The following python script will
merge all this data and calculate the final histogram together with the appropriate error bars.
import math
import glob
import numpy as np
#Here are some numbers you will need to change if you run this script on grids generated in different
contexts
nquantities = 1
#Number of quanities that have been evaluated on the grid
grid_dimension = 1
#Number of collective variables that you provided using the ARG keyword
filename = "my_histogram.dat" # The name you specified the data to output to in the DUMPGRID command
# Function to read in histogram data and normalization
def readhistogram( fname ) :
# Read in the histogram data
data = np.loadtxt( fname )
with open( filename, "r" ) as myfile :
for line in myfile :
if line.startswith("#! SET normalisation") : norm = line.split()[3]
return float(norm), data
# Read in the grid file header to work out what fields we have
with open( filename, "r" ) as myfile :
for line in myfile :
if line.startswith("#! FIELDS") : fieldnames = line.split()
# Check if derivatives have been output in the grid by investigating the header
nextg = 1
if len(fieldnames)>(2+grid_dimension+nquantities) :
nextg = 1 + grid_dimension
assert len(fieldnames)==(2+grid_dimension + nquantities*nextg)
# Read in a grid
norm, griddata = readhistogram( filename )
norm2 = norm*norm
# Create two np array that will be used to accumulate the average grid and the average grid squared
average = np.zeros((nquantities, len(griddata[:,0])))
average_sq = np.zeros((nquantities, len(griddata[:,0])))
for i in range(0,nquantities) :
average[i,:] = norm*griddata[:,nquantities+i*nextg]
average_sq[i,:] = norm*griddata[:,nquantities+i*nextg]*griddata[:,nquantities+i*nextg]
# Now sum the grids from all all the analysis files you have
for filen in glob.glob( "analysis.*." + filename ) :
tnorm, newgrid = readhistogram( filen )
norm = norm + tnorm
norm2 = norm2 + tnorm*tnorm
for i in range(0,nquantities) :
average[i,:] = average[i,:] + tnorm*newgrid[:,nquantities+i*nextg]
average_sq[i,:] = average_sq[i,:] + tnorm*newgrid[:,nquantities+i*nextg]*newgrid[:,
nquantities+i*nextg]
# Compte the final average grid
average = average / norm
# Compute the sample variance for all grid points
Generated by Doxygen
696
Tutorials
variance = (average_sq / norm) - average*average
# Now multiply by bessel correction to unbias the sample variance and get the population variance
variance = ( norm /(norm-(norm2/norm)) ) * variance
# And lastly divide by number of grids and square root to get an error bar for each grid point
ngrid = 1 + len( glob.glob( "analysis.*." + filename ) )
errors = np.sqrt( variance / ngrid )
# Calculate average error over grid and output in header
for i in range(0,nquantities) :
mean_error = sum(errors[i,:]) / len(errors[i,:])
print("# Average error for " + str(i+1) + "th averaged function on grid equals ", mean_error )
# Output the final average grid
for i in range(0,len(griddata[:,0])) :
for j in range(0,grid_dimension) : print( griddata[i,j], end=" " )
for j in range(0,nquantities) : print( average[j,i], errors[j,i], end=" " )
print()
Copy this script to a file called merge-histograms.py and then run its contents by executing the command:
> python merge-histograms.py > final-histogram.dat
This will output the final average histogram together with some error bars. You can plot this function using gnuplot
by executing the command:
gnuplot> p ’final-histogram.dat’ u 1:2:3 w e, ’’ u 1:2 w l
Where are the error bars in our estimate of the histogram the largest? Why are the errors large in these
regions?
Notice that the file output by the script above also contains information on the average error per grid point in the
header. The quantity that is calculated here is:
average error = N1
N
X
σi
i=1
In this expression N is the total number of grid points at which the function was evaluated and σi is the error bar
for the estimate of the function that was calculated for the ith grid point. The average error is a useful quantity
as we can plot it and thus check that our blocks are large enough to correct for the correlation between our data
points. In other words, we can use this quantity in the same way that we used the error around the average in
Problem III: Dealing with correlated variables. A plot of the average error versus the size of the blocks that were
used in for the block averaging is shown below. This figure demonstrates that a block average length of 500 is
certainly long enough to correct for the problems due to the correlations in the values produced at different times:
If you have sufficient time try to see if you can reproduce this plot using the data you generated
11.2.5
Extensions
The exercises in the previous sections have shown you how we can calculate ensemble averages from trajectory
data. You should have seen that performing block averaging is vital as this technique allows us to deal with the
artifacts that we get because of the correlations in the data that we obtain from simulation trajectories.
What we have seen is that when this technique is used correctly we get reasonable error bars. If block averaging
is not performed, however, we can underestimate the errors in our data and thus express a false confidence in the
reliability of our simulation results.
The next step for you will be to use this technique when analyzing the data from your own simulations.
Generated by Doxygen
11.3 Trieste tutorial: Using restraints
11.3
Trieste tutorial: Using restraints
11.3.1
Aims
697
The aim of this tutorial is to introduce the users to the use of constant biases in PLUMED.
11.3.2
Objectives
• Apply a restraint on a simulations over one or more collective variables
• Understand the effect of a restraint on the acquired statistics
• Perform a simple un-biasing of a restrained simulation
• Add an external potential in the form of an analytical or numerical function
11.3.3
Resources
TheTARBALL for this tutorial contains the following files:
• wdimer.pdb: a PDB file for two molecules of water in vacuo
• wdimer.tpr: a GROMACS run file to perform MD of two water molecules
• diala.pdb: a PDB file for alanine dipeptide in vacuo
• diala.tpr: a GROMACS run file to perform MD of alanine dipeptide
• do_block_histo.py: the python script from Trieste tutorial: Averaging, histograms and block analysis to perform block averaging over histograms
This tutorial has been tested on a pre-release version of version 2.4. However, it should not take advantage of
2.4-only features, thus should also work with version 2.3.
11.3.4
Introduction
PLUMED can calculate conformational properties of a system a posteriori as well as on-the-fly. This information can
be use to manipulate a simulation on-the-fly. This means adding energy terms in addition to those of the original
Hamiltonian. This additional energy terms are usually referred as Bias. In the following we will see how to apply a
constant bias potential with PLUMED. It is preferable to run each exercise in a separate folder.
Generated by Doxygen
698
11.3.4.1
Tutorials
Biased sampling
A system at temperature T samples conformations from the canonical ensemble:
P (q) ∝ e
U (q)
BT
−k
. Here q are the microscopic coordinates and kB is the Boltzmann constant. Since q is a highly dimensional vector, it
is often convenient to analyze it in terms of a few collective variables (see Trieste tutorial: Analyzing trajectories using PLUMED
). The probability distribution for a CV s is
Z
P (s) ∝
U (q)
BT
−k
dqe
δ(s − s(q))
This probability can be expressed in energy units as a free energy landscape F (s):
F (s) = −kB T log P (s)
.
Now we would like to modify the potential by adding a term that depends on the CV only. That is, instead of using
U (q), we use U (q) + V (s(q)). There are several reasons why one would like to introduce this potential. One is
to avoid that the system samples some un-desired portion of the conformational space. As an example, imagine
that you want to study dissociation of a complex of two molecules. If you perform a very long simulation you will
be able to see association and dissociation. However, the typical time required for association will depend on the
size of the simulation box. It could be thus convenient to limit the exploration to conformations where the distance
between the two molecules is lower than a given threshold. This could be done by adding a bias potential on the
distance between the two molecules. Another example is the simulation of a portion of a large molecule taken out
from its initial context. The fragment alone could be unstable, and one might want to add additional potentials to
keep the fragment in place. This could be done by adding a bias potential on some measure of the distance from
the experimental structure (e.g. on root-mean-square deviation).
Whatever CV we decide to bias, it is very important to recognize which is the effect of this bias and, if necessary,
remove it a posteriori. The biased distribution of the CV will be
P 0 (s) ∝
Z
−
dqe
U (q)+V (s(q))
kB T
δ(s − s(q)) ∝ e
−
V (s(q))
kB T
P (s)
and the biased free energy landscape
F 0 (s) = −kB T log P 0 (s) = F (s) + V (s) + C
Thus, the effect of a bias potential on the free energy is additive. Also notice the presence of an undetermined
constant C . This constant is irrelevant for what concerns free-energy differences and barriers, but will be important
later when we will learn the weighted-histogram method. Obviously the last equation can be inverted so as to obtain
the original, unbiased free-energy landscape from the biased one just subtracting the bias potential
F (s) = F 0 (s) − V (s) + C
Additionally, one might be interested in recovering the distribution of an arbitrary observable. E.g., one could
add a bias on the distance between two molecules and be willing to compute the unbiased distribution of some
torsional angle. In this case there is no straightforward relationship that can be used, and one has to go back to the
relationship between the microscopic probabilities:
P (q) ∝ P 0 (q)e
V (s(q))
kB T
The consequence of this expression is that one can obtained any kind of unbiased information from a biased
simulation just by weighting every sampled conformation with a weight
w∝e
V (s(q))
kB T
That is, frames that have been explored in spite of a high (disfavoring) bias potential V will be counted more than
frames that has been explored with a less disfavoring bias potential.
We will make use of two toy models: the first is a water dimer, i.e. two molecules of water in vacuo, that we will use
to compare the effect of a constant bias on the equilibrium properties of the system that in this case can be readily
computed. The second toy model is alanine dipeptide in vacuo. This system is more challenging to characterize
with a standard MD simulation and we will see how we can use an interactive approach to to build a constant bias
that will help in flattening the underlying free energy surface and thus sped up the sampling.
Generated by Doxygen
11.3 Trieste tutorial: Using restraints
699
Note
Create a folder for each exercise and use sub-folders if you want to run the same simulation with multiple
choices for the parameters
11.3.5
Exercise 1: converged histogram of the water dimer relative distance
First of all let's start to learn something about the water dimer system by running a first simulations. You can start
by creating a folder with the dimer.tpr file and run a simulation.
> gmx mdrun -s dimer.tpr
In this way we have a 25ns long trajectory that we can use to have a first look at the behavior of the system. Is the
sampling of the relative distance between the two water molecules converged?
Use plumed driver to analyze the trajectory and evaluate the quality of the sampling.
Here you can find a sample plumed.dat file that you can use as a template. Whenever you see an highlightedF←ILL string, this is a string that you should replace.
BEGIN_PLUMED_FILE
# vim:ft=plumed
#compute the distance between the two oxygens
d: DISTANCE ATOMS=1,4
#accumulate block histograms
hh: HISTOGRAM ARG=d STRIDE=10 GRID_MIN=0 GRID_MAX=4.0 GRID_BIN=200 KERNEL=DISCRETE CLEAR=10000
#and dump them
DUMPGRID GRID=hh FILE=my_histogram.dat STRIDE=10000
# Print the collective variable.
PRINT ARG=d STRIDE=10 FILE=distance.dat
> plumed driver --mf_xtc traj_comp.xtc --plumed plumed.dat
> python3 do_block_histo.py > final-histo-10000.dat
If there is something you don't remember about this procedure go back and check in Trieste tutorial: Averaging, histograms and block a
. There you can also find a python script to perform block averaging of the histograms and assess the error. The
result should be comparable with the following: Notice the peak at 0.9 nm, this is the effect of using cut-off for the
calculation of the interactions in the simulation (check the run-dimer.mdp file for the properties of the run)
11.3.6
Exercise 2: Apply a linear restraint on the same collective variable
Now we will try to apply a linear restraint on the relative distance and compare the resulting distribution. The new
sampling will reflect the effect of the bias. Be careful about the statistics: in the simulation of exercise 1 you were
post processing a trajectory of 125000 frames accumulating one frame every ten in an histogram and clearing the
histogram after 10000 steps. As a result you had 12 blocks in the form of 11 analysis.∗ files and a final block named
my_histogram.dat. In the following try to accumulate on the fly the same amount of statistics. Look into the .mdp
file to see how often frames are written in a trajectory. If you write too many analysis.∗ files (i.e. 100 files plumed
will fail with an error).
Generated by Doxygen
700
Tutorials
BEGIN_PLUMED_FILE
# vim:ft=plumed
#compute the distance between the two oxygens
d: DISTANCE __FILL__
#accumulate block histograms
hh: HISTOGRAM ARG=d KERNEL=DISCRETE STRIDE=500 CLEAR=500000 GRID_MIN=0 GRID_MAX=4.0 GRID_BIN=200
#and dump them
DUMPGRID __FILL__
#apply a linear restraint
lr: RESTRAINT ARG=d KAPPA=0 AT=0 SLOPE=2.5
# Print the collective variable and the bias.
PRINT __FILL__
In a new folder we can run this new simulation this time biasing and analyzing the simulation on-the-fly.
> gmx mdrun -s dimer.tpr -plumed plumed.dat
The histogram should look different.
The effect of a constant bias is that of systematically changing the probability of each conformation by a factor
exp(+Vbias /kB T ). This means that it is easily possible to recover the un-biased distribution at least in the regions
of the conformational space that have been thoroughly sampled. In practice the statistical weight of each frame is
not 1 anymore but is given by the exponential of the bias.
In order to recover the unbiased distribution we can post process the simulation using plumed driver to recalculate
the bias felt by each frame and store this information to analyze any property. Furthermore plumed can also
automatically use the bias to reweight the accumulated histogram.
BEGIN_PLUMED_FILE
# vim:ft=plumed
d: DISTANCE __FILL__
lr: RESTRAINT __FILL__
as: REWEIGHT_BIAS TEMP=298
HISTOGRAM ...
LOGWEIGHTS=as
ARG=d
STRIDE=10
GRID_MIN=0 GRID_MAX=4.0 GRID_BIN=200
KERNEL=DISCRETE
CLEAR=10000
... HISTOGRAM
DUMPGRID __FILL__
PRINT ARG=*.* FILE=COLVAR STRIDE=1
Be careful again about the difference in the way statistics is accumulated on-the-fly or for post processing. This is
not critical for the result but is important in order to have comparable histograms, that is histograms with comparable
noise. Remember to give different names to the new histogram otherwise the one obtained before will be overwritten.
> plumed driver --mf_xtc traj_comp.xtc --plumed plumed.dat
Note
To run block analysis of both sets of histograms you need to edit the python script because the file name is
hard coded.
> python3 do_block_histo.py > histo-biased.dat
> python3 do_block_histo.py > histo-reweighted.dat
Now the resulting histogram should be comparable to the reference one.
Generated by Doxygen
11.3 Trieste tutorial: Using restraints
11.3.7
701
Exercise 3: Apply a quadratic restraint on the same collective variable
Do you expect a different behavior? This time we can write the plumed input file in such a way to compare directly
the biased and unbiased histograms.
BEGIN_PLUMED_FILE
# vim:ft=plumed
#calculate the distance
d: DISTANCE ATOMS=1,4
#apply the quadratic restraint centered at a distance of 0.5 nm
lr: RESTRAINT ARG=d KAPPA=10 AT=0.5
#accumulate the biased histogram
hh: HISTOGRAM ARG=d STRIDE=500 GRID_MIN=0 GRID_MAX=4.0 GRID_BIN=200 KERNEL=DISCRETE CLEAR=500000
#dumpit
DUMPGRID GRID=hh FILE=my_histogram.dat STRIDE=500000
#calculate the weights from the constant bias
as: REWEIGHT_BIAS TEMP=298
#accumulate the unbiased histogram
hhu: HISTOGRAM ARG=d STRIDE=500 GRID_MIN=0 GRID_MAX=4.0 GRID_BIN=200 KERNEL=DISCRETE CLEAR=500000 LOGWEIGHTS=a
#dumpit
DUMPGRID GRID=hhu FILE=myhistu.dat STRIDE=500000
#print distance and bias
PRINT ARG=d,lr.bias FILE=distance.dat STRIDE=50
The comparison of the two histograms with the former will show the effect of the weak quadratic bias on the simulation.
Note
To run block analysis of both sets of histograms you need to edit the python script because the file name is
hard coded.
> python3 do_block_histo.py > histo-biased.dat
> python3 do_block_histo.py > histo-reweighted.dat
11.3.8
Exercise 4: Apply an upper wall on the distance.
In the above cases we have always applied weak biases. Sometimes biases are useful to prevent the system in
reaching some region of the conformational space. In this case instead of using RESTRAINT , we can make use of
lower or upper restraints, e.g. LOWER_WALLS and UPPER_WALLS.
What happen to the histogram when we use walls?
BEGIN_PLUMED_FILE
# vim:ft=plumed
d: DISTANCE ATOMS=1,4
uw: UPPER_WALLS ARG=d KAPPA=1000 AT=2.5
# accumulate the biased histogram
__FILL__
#dumpit
__FILL__
# calcualte the weights from the constant bias
__FILL__
#accumulate the unbiased histogram
__FILL__
#dumpit
__FILL__
#print distance and bias
__FILL__
Run it.
> gmx mdrun -s dimer.tpr -plumed plumed.dat
If we have not sampled a region thoroughly enough it is not possible to estimate the histogram in that region even
using reweighting (reweighting is not magic!).
Generated by Doxygen
702
Tutorials
11.3.9
Exercise 5: Evaluate the free energy and use it as an external restraint
The main issue in sampling rare events is that importance sampling algorithms spend more time in low energy
regions and if two low energy regions are separated by a high energy one is unlikely for the sampling algorithm to
cross the high energy region and reach the other low energy one. From this point of view an algorithm based on
random sampling will work better in crossing the barrier. A particularly efficient sampling can be obtained if one
would know the underlying free energy and thus use that to bias the sampling and make the sampling probability
uniform in the regions of relevant interest. In this exercise we will make use of the free-energy estimate along the
distance collective variable to bias the sampling of the same collective variable in the dimer simulation. To do so we
will make use of a table potential applied using the Bias EXTERNAL. We first need to get a smooth estimate of the
free-energy from our fist reference simulations, we will do this by accumulating a histogram with kernel functions,
that is continuous function centered at the value of the accumulated point and added accumulated on the discrete
representation of the histogram, see Kernel density estimation .
BEGIN_PLUMED_FILE
# vim:ft=plumed
#calculate the distance
d: DISTANCE ATOMS=1,4
#accumulate the histogram using a gaussian kernel with 0.05 nm width
hh2: HISTOGRAM ARG=d STRIDE=10 GRID_MIN=0 GRID_MAX=4.0 GRID_BIN=400 BANDWIDTH=0.05
#convert to a free energy
ff: CONVERT_TO_FES GRID=__FILL__ TEMP=__FILL__
#dump the free energy
DUMPGRID GRID=__FILL__ FILE=__FILL__
by running plumed driver on the reference trajectory we obtain a free energy estimate.
> plumed driver --mf_xtc traj_comp.xtc --plumed plumed.dat
The resulting file for the free energy should be edited in order to:
• Invert the sign of the free-energy and of its derivative
• Remove some unused flag and regions with infinite potential at the boundaries
The file looks like:
#! FIELDS d ff dff_d
#! SET min_d 0
#! SET max_d 4.0
#! SET nbins_d 400
#! SET periodic_d false
0.060000 -34.9754 185.606
0.070000 -26.0117 184.362
0.080000 -20.8195 181.39
0.090000 -17.5773 176.718
where the first column is the grid spacing, the second the free energy and the third the derivative of the free energy.
You can edit the file as you want, for example using the following bash lines:
grep \# ff.dat | grep -v normalisation > external.dat
grep -v \# ff.dat | awk ’{print $1, -$2, -$3}’ | grep -v inf >> external.dat
Furthermore edit the first line of external.dat from
Generated by Doxygen
11.3 Trieste tutorial: Using restraints
703
#! FIELDS d ff dff_d
to
#! FIELDS d ff.bias der_d
Now we have an external potential that is the opposite of the free energy and we can use it in a new folder to bias a
simulation:
BEGIN_PLUMED_FILE
# vim:ft=plumed
d: DISTANCE ATOMS=1,4
EXTERNAL ARG=d FILE=__FILL__ LABEL=ff
# accumulate the biased histogram
__FILL__
#dumpit
__FILL__
# calcualte the weights from the constant bias
__FILL__
#accumulate the unbiased histogram
__FILL__
#dumpit
__FILL__
#print distance and bias
__FILL__
Run it.
> gmx mdrun -s dimer.tpr -plumed plumed.dat
How do the biased and unbiased histograms look like? In the following we will apply this concept to sample the
conformational space of a more complex system.
11.3.10
Exercise 6: Preliminary run with Alanine dipeptide
Alanine dipeptide is characterized by multiple minima separated by relatively high free energy barriers. Here we will
explore the conformational space of alanine dipeptide using a standard MD simulation, then instead of using the
free energy as an external potential we will try to fit the potential using gnuplot and add a bias using an analytical
function of a collective variable with MATHEVAL and BIASVALUE .
As a first test lets run an MD and generate on-the-fly the free energy as a function of the phi and psi collective
variables separately.
BEGIN_PLUMED_FILE
# vim:ft=plumed
MOLINFO STRUCTURE=aladip.pdb
phi: TORSION ATOMS=@phi-2
psi: TORSION ATOMS=@psi-2
hhphi: HISTOGRAM ARG=phi STRIDE=10 GRID_MIN=-pi GRID_MAX=pi GRID_BIN=600 BANDWIDTH=0.05
hhpsi: HISTOGRAM ARG=psi STRIDE=10 GRID_MIN=-pi GRID_MAX=pi GRID_BIN=600 BANDWIDTH=0.05
ffphi: CONVERT_TO_FES GRID=hhphi TEMP=298
ffpsi: CONVERT_TO_FES GRID=hhpsi TEMP=298
DUMPGRID GRID=ffphi FILE=ffphi.dat
DUMPGRID GRID=ffpsi FILE=ffpsi.dat
PRINT ARG=phi,psi FILE=colvar.dat STRIDE=10
Generated by Doxygen
704
Tutorials
from the colvar file it is clear that we can quickly explore two minima but that the region for positive phi is not
accessible. Instead of using the opposite of the free energy as a table potential here we introduce the function
MATHEVAL that allows defining complex analytical functions of collective variables, and the bias BIASVALUE that
allows using any continuous function of the positions as a bias.
So first we need to fit the opposite of the free energy as a function of phi in the region explored with a periodic
function, because of the gaussian like look of the minima we can fit it using the von Mises distribution.
In gnuplot
>gnuplot
gnuplot>plot ’ffphi.dat’ u 1:(-$2+31) w l
gnuplot>f(x)=exp(k1*cos(x-a1))+exp(k2*cos(x-a2))
gnuplot>fit [-3.:-0.6] f(x) ’ffphi.dat’ u 1:(-$2+31) via k1,a1,k2,a2
gnuplot>rep f(x)
The function and the resulting parameters can be used to run a new biased simulation:
11.3.11
Exercise 7: First biased run with Alanine dipeptide
BEGIN_PLUMED_FILE
# vim:ft=plumed
MOLINFO STRUCTURE=aladip.pdb
phi: TORSION ATOMS=@phi-2
__FILL__
MATHEVAL ...
ARG=phi
LABEL=doubleg
FUNC=exp(__FILL)+__FILL__
PERIODIC=NO
... MATHEVAL
b: BIASVALUE ARG=__FILL__
PRINT __FILL__
It is now possible to run a second simulation and observe the new behavior. The system quickly explores a new
minimum. While a quantitative estimate of the free energy difference of the old and new regions is out of the scope
of the current exercise what we can do is to add a new von Mises function centered in the new minimum with a
comparable height, in this way we can hope to facilitate a back and forth transition along the phi collective variable.
>gnuplot
gnuplot> ...
We can now run a third simulation where both regions are biased.
11.3.12
Exercise 8: Second biased run with Alanine dipeptide
BEGIN_PLUMED_FILE
# vim:ft=plumed
MOLINFO STRUCTURE=aladip.pdb
phi: TORSION ATOMS=@phi-2
psi: TORSION ATOMS=@psi-2
MATHEVAL ...
ARG=phi
Generated by Doxygen
11.4 Trieste tutorial: Metadynamics simulations with PLUMED
705
LABEL=tripleg
FUNC=exp(k1*cos(x-a1))+exp(k2*cos(x-a2))+exp(k3*cos(x+a3))
PERIODIC=NO
... MATHEVAL
b: BIASVALUE ARG=tripleg
__FILL__
ENDPLUMED
With this third simulation it should be possible to visit both regions as a function on the phi torsion. Now it is possible
to reweight the sampling and obtain a better free energy estimate along phi.
BEGIN_PLUMED_FILE
# vim:ft=plumed
MOLINFO STRUCTURE=aladip.pdb
phi: TORSION ATOMS=@phi-2
psi: TORSION ATOMS=@psi-2
MATHEVAL ...
ARG=phi
LABEL=tripleg
FUNC=__FILL__
PERIODIC=NO
... MATHEVAL
b: BIASVALUE ARG=tripleg
as: REWEIGHT_BIAS TEMP=298
hhphi: HISTOGRAM ARG=phi STRIDE=10 GRID_MIN=-pi GRID_MAX=pi GRID_BIN=600 BANDWIDTH=0.05 LOGWEIGHTS=as
hhpsi: HISTOGRAM ARG=psi STRIDE=10 GRID_MIN=-pi GRID_MAX=pi GRID_BIN=600 BANDWIDTH=0.05 LOGWEIGHTS=as
ffphi: CONVERT_TO_FES GRID=hhphi TEMP=298
ffpsi: CONVERT_TO_FES GRID=hhpsi TEMP=298
DUMPGRID GRID=ffphi FILE=ffphi.dat
DUMPGRID GRID=ffpsi FILE=ffpsi.dat
PRINT ARG=phi,psi FILE=colvar.dat STRIDE=10
If you have time you can extend this in two-dimensions using at the same time the phi and psi collective variables.
11.4
Trieste tutorial: Metadynamics simulations with PLUMED
11.4.1
Aims
The aim of this tutorial is to train users to perform metadynamics simulations with PLUMED, analyze the results,
calculating free-energies as a function of the collective variables used, and estimating the associated error.
11.4.2
Objectives
Once this tutorial is completed students will be able to:
• Write the PLUMED input file to perform metadynamics simulations
• Calculate the free energy from a metadynamics run
• Compute the error associated to the reconstructed free energy
• Evaluate the convergence of a metadynamics simulation
• Assess the choice of the collective variables
Generated by Doxygen
706
Tutorials
11.4.3
Resources
TheTARBALL for this project contains the following files:
• diala.pdb: a PDB file for alanine dipeptide in vacuo
• topol.tpr: a GROMACS run file to perform MD of alanine dipeptide
• do_block_fes.py: a python script to perform error analysis
This tutorial has been tested on a pre-release version of version 2.4. However, it should not take advantage of
2.4-only features, thus should also work with version 2.3.
Note
We suggest to run the three exercises in three separate directories. For Exercise 3, you will need the output
of the first two exercises, so don't delete it!
11.4.4
Introduction
We have seen that PLUMED can be used to compute collective variables. However, PLUMED is most often use
to add forces on the collective variables. To this aim, we have implemented a variety of possible biases acting on
collective variables. The complete documentation for all the biasing methods available in PLUMED can be found at
the Bias page. In the following we will see how to build an adaptive bias potential with metadynamics. Here you can
find a brief recap of the metadynamics theory.
In metadynamics, an external history-dependent bias potential is constructed in the space of a few selected degrees
of freedom ~
s(q), generally called collective variables (CVs) [45]. This potential is built as a sum of Gaussian kernels
deposited along the trajectory in the CVs space:
V (~s, t) =
X
W (kτ ) exp −
d
X
(si − si (q(kτ )))2
i=1
kτ gmx mdrun -s topol.tpr -nsteps 5000000 -plumed plumed.dat
During the metadynamics simulation, PLUMED will create two files, named COLVAR and HILLS. The COLVAR file
contains all the information specified by the PRINT command, in this case the value of the CVs every 10 steps of
simulation, along with the current value of the metadynamics bias potential. We can use gnuplot to visualize the
behavior of the CV during the simulation, as reported in the COLVAR file:
gnuplot> p "COLVAR" u 1:2
By inspecting Figure trieste-4-phi-fig, we can see that the system is initialized in one of the two metastable states
of alanine dipeptide. After a while (t=0.1 ns), the system is pushed by the metadynamics bias potential to visit the
other local minimum. As the simulation continues, the bias potential fills the underlying free-energy landscape, and
the system is able to diffuse in the entire phase space.
The HILLS file contains a list of the Gaussian kernels deposited along the simulation. If we give a look at the header
of this file, we can find relevant information about its content:
#!
#!
#!
#!
FIELDS time phi sigma_phi height biasf
SET multivariate false
SET min_phi -pi
SET max_phi pi
The line starting with FIELDS tells us what is displayed in the various columns of the HILLS file: the simulation time,
the instantaneous value of φ, the Gaussian width and height, and the bias factor. We can use the HILLS file to
visualize the decrease of the Gaussian height during the simulation, according to the well-tempered recipe:
If we look carefully at the scale of the y-axis, we will notice that in the beginning the value of the Gaussian height is
higher than the initial height specified in the input file, which should be 1.2 kJ/mol. In fact, this column reports the
height of the Gaussian scaled by the pre-factor that in well-tempered metadynamics relates the bias potential to the
free energy.
Generated by Doxygen
11.4 Trieste tutorial: Metadynamics simulations with PLUMED
11.4.5.2
709
Exercise 1b: estimating the free energy
One can estimate the free energy as a function of the metadynamics CVs directly from the metadynamics bias
potential. In order to do so, the utility sum_hills should be used to sum the Gaussian kernels deposited during the
simulation and stored in the HILLS file.
To calculate the free energy as a function of φ, it is sufficient to use the following command line:
plumed sum_hills --hills HILLS
The command above generates a file called fes.dat in which the free-energy surface as function of φ is calculated
on a regular grid. One can modify the default name for the free energy file, as well as the boundaries and bin size
of the grid, by using the following options of sum_hills :
--outfile --min - the
--max - the
--bin - the
--spacing -
specify the outputfile for sumhills
lower bounds for the grid
upper bounds for the grid
number of bins for the grid
grid spacing, alternative to the number of bins
The result should look like this:
To assess the convergence of a metadynamics simulation, one can calculate the estimate of the free energy as a
function of simulation time. At convergence, the reconstructed profiles should be similar. The option --stride should
be used to give an estimate of the free energy every N Gaussian kernels deposited, and the option --mintozero can
be used to align the profiles by setting the global minimum to zero. If we use the following command line:
plumed sum_hills --hills HILLS --stride 100 --mintozero
one free energy is calculated every 100 Gaussian kernels deposited, and the global minimum is set to zero in all
profiles. The resulting plot should look like the following:
These two qualitative observations:
• the system is diffusing efficiently in the collective variable space (Figure trieste-4-phi-fig)
• the estimated free energy does not change significantly as a function of time (Figure trieste-4-metad-phifest-fig)
suggest that the simulation most likely converged.
Warning
The fact that the Gaussian height is decreasing to zero should not be used as a measure of convergence of
your metadynamics simulation!
Note
The two observations above are necessary, but qualitative conditions for convergence. A quantitative assessment of convergence can be obtained by performing an error analysis of the reconstructed free-energy profile,
as explained in the last exercise
Generated by Doxygen
710
11.4.6
Tutorials
Exercise 2: playing with collective variables
In this exercise, we will run a well-tempered metadynamics simulation on alanine dipeptide in vacuum, this time
using as CV the backbone dihedral ψ . Please complete the template plumed.dat file used in the previous
exercise to run this calculation.
Once your plumed.dat file is complete, you can run a 10-ns long metadynamics simulations with the following
command
> gmx mdrun -s topol.tpr -nsteps 5000000 -plumed plumed.dat
As we did in the previous exercise, we can use COLVAR to visualize the behavior of the CV during the simulation.
Here we will plot at the same time the evolution of the metadynamics CV ψ and of the other dihedral φ.
gnuplot> p "COLVAR" u 1:2, "" u 1:3
By inspecting Figure trieste-4-metad-psi-phi-fig, we notice that something different happened compared to the previous exercise. At first the behavior of ψ looks diffusive in the entire CV space. However, around t=1 ns, ψ seems
trapped in a region of the CV space in which it was previously diffusing without problems. The reason is that the
non-biased CV φ after a while has jumped into a different local minima. Since φ is not directly biased, one has to
wait for this (slow) degree of freedom to equilibrate before the free energy along ψ can converge.
Try to repeat the analysis done in the previous exercise, i.e. calculate the estimate of the free energy as a function
of time, first step to assess the convergence of this metadynamics simulation.
11.4.7
Exercise 3: estimating the error in free-energies using block-analysis
In this exercise, we will calculate the error associated to the free-energy reconstructed by a well-tempered metadynamics simulation. The free energy and the errors will be calculated using the block-analysis technique explained
in a previous lesson (Trieste tutorial: Averaging, histograms and block analysis). The procedure can be used to estimate the error in the free-energy as a function of the collective variable(s) used in the metadynamics simulation,
or for any other function of the coordinates of the system.
First, we will calculate the "un-biasing" weights associated to each conformation sampled during the metadynamics
run. In order to calculate these weights, we can use either of these two approaches:
1) Weights are calculated by considering the time-dependence of the metadynamics bias potential [3];
2) Weights are calculated using the metadynamics bias potential obtained at the end of the simulation and assuming
a constant bias during the entire course of the simulation [48].
In this exercise we will use the umbrella-sampling-like reweighting approach (Method 2).
To calculate the weights, we need to use the PLUMED driver utility and read the HILLS file along with the GR←OMACS trajectory file produced during the metadynamics simulation. Let's consider the metadynamics simulation
carried out in Exercise 1. We need to prepare the plumed.dat input file to use in combination with driver. Here
you can find a sample plumed.dat file that you can use as a template. Whenever you see an highlightedFILL
string, this is a string that you should replace.
Generated by Doxygen
11.4 Trieste tutorial: Metadynamics simulations with PLUMED
711
BEGIN_PLUMED_FILE
# Read old Gaussians deposited on HILLS file
RESTART
# Compute the backbone dihedral angle phi, defined by atoms C-N-CA-C
phi: TORSION ATOMS=__FILL__
# Compute the backbone dihedral angle psi, defined by atoms N-CA-C-N
psi: TORSION ATOMS=__FILL__
# Activate well-tempered metadynamics in phi
metad: __FILL__ ARG=__FILL__ ...
# Set the deposition stride to a large number
PACE=10000000 HEIGHT=1.2 BIASFACTOR=__FILL__
# Gaussian width (sigma) should be chosen based on CV fluctuation in unbiased run
SIGMA=__FILL__
# Gaussians will be read from file and stored on grid
FILE=HILLS GRID_MIN=-pi GRID_MAX=pi
...
# Print both collective variables and the value of the bias potential on COLVAR file
PRINT ARG=__FILL__ FILE=COLVAR STRIDE=1
Once your plumed.dat file is complete, you can use the driver utility to back-calculated the quantities needed for
the error calculation
plumed driver --plumed plumed.dat --mf_xtc traj_comp.xtc
The COLVAR file produced by driver should look like this:
#! FIELDS time phi
#! SET min_phi -pi
#! SET max_phi pi
#! SET min_psi -pi
#! SET max_psi pi
0.000000 0.907347
1.000000 0.814296
2.000000 1.118951
3.000000 1.040781
4.000000 1.218571
psi metad.bias
-0.144312
-0.445819
-0.909782
-0.991788
-1.020024
103.117323
100.974351
104.329630
104.559590
102.744053
Please check your plumed.dat file if your output looks different! Once the final bias has been evaluated on the
entire metadynamics simulations, we can easily calculate the "un-biasing weights" using the umbrella-sampling-like
approach:
# find maximum value of bias
bmax=‘awk ’BEGIN{max=0.}{if($1!="#!" && $4>max)max=$4}END{print max}’ COLVAR‘
# print phi values and weights
awk ’{if($1!="#!") print $2,exp(($4-bmax)/kbt)}’ kbt=2.494339 bmax=$bmax COLVAR > phi.weight
If you inspect the phi.weight file, you will see that each line contains the value of the dihedral φ along with the
corresponding weight:
0.907347
0.814296
1.118951
1.040781
1.218571
1.090823
1.130800
0.0400579
0.0169656
0.0651276
0.0714174
0.0344903
0.0700568
0.0622998
Generated by Doxygen
712
Tutorials
At this point we can apply the block-analysis technique we have learned in the Trieste tutorial: Averaging, histograms and block analysis
tutorial to calculate for different block sizes the average free-energy and the error. For your convenience, you can
use the do_block_fes.py python script to read the phi.weight file and produce the desired output. We
use a bash loop to use block sizes ranging from 1 to 1000:
for i in ‘seq 1 10 1000‘; do python3 do_block_fes.py phi.weight 1 -3.141593 3.018393 51 2.494339 $i; done
For each value of block length N, you will obtain a separate fes.N.dat file, containing the value of the φ variable
on a grid, the average free-energy, and the associated error (in kJ/mol):
-3.141593
-3.018393
-2.895194
-2.771994
-2.648794
23.184653
17.264462
13.360259
10.772696
9.403544
0.080659
0.055181
0.047751
0.043548
0.042022
Finally, we can calculate the average error along the free-energy profile as a function of the block length:
for i in ‘seq 1 10 1000‘; do a=‘awk ’{tot+=$3}END{print tot/NR}’ fes.$i.dat‘; echo $i $a; done > err.blocks
and visualize it using gnuplot:
gnuplot> p "err.blocks" u 1:2 w lp
As expected, the error increases with the block length until it reaches a plateau in correspondence of a dimension
of the block that exceeds the correlation between data points (Fig. trieste-4-block-phi).
To complete this exercise, you should do the following:
• calculate the error associated to the free energy as a function of the collective variable ψ from Exercise 1
• calculate the error associated to the free energy as a function of the collective variable ψ from Exercise 2
• compare the different behaviors in Exercise 1 and 2
What can we learn from this analysis about the convergence of the two metadynamics simulations and the quality
of the collective variables chosen?
At this time, the most important question of this lecture becomes:
• Could we distinguish the different behavior (in terms of convergence) of the simulations in Exercise 1 and 2
simply by looking at the time series of the Gaussian height?
11.4.8
Conclusions
In summary, in this tutorial you should have learned how to use PLUMED to:
• Setup and run a metadynamics calculation.
• Compute free energies from the metadynamics bias potential using the sum_hills utility.
• Calculate the error in the reconstructed free energy using block analysis.
• Discriminate between good and bad collective variables.
• Evaluate the convergence of a metadynamics simulation.
Generated by Doxygen
11.5 Trieste tutorial: Running and analyzing multi-replica simulations.
11.5
Trieste tutorial: Running and analyzing multi-replica simulations.
11.5.1
Aims
713
The aim of this tutorial is to show how to use PLUMED to run simulations with multiple replicas and how to analyze
them. In particular, we will focus on cases where the replicas feel different biasing potentials.
11.5.2
Objectives
Once this tutorial is completed students will be able to:
• Write plumed input files suitable for multi-replica simulations.
• Run replica exchange simulations with gromacs and plumed using different bias potentials in each replica.
• Analyze replica exchange simulations using WHAM so as to obtain the weight of each snapshot.
11.5.3
Resources
TheTARBALL for this project contains the following files:
• topol0.tpr, topol1.tpr, topol2.tpr, and topol3.tpr, gromacs input files for analine dipeptide. Notice that two of them (0 and 2) are initialized in one free-energy well and two of them (1 and 3) in the
other free-energy well.
• A directory SCRIPT that contains a wham.py script to perform WHAM. Notice that this required python 3
(does not work with python 2).
• A directory SETUP with the gromacs input file that can be used to generate new tpr files.
This tutorial has been tested on a pre-release version of version 2.4. In particular, it takes advantage of a special
syntax for setting up multi-replica simulations that is only available since version 2.4. Exercise could be done also
with version 2.3 but using a different syntax with respect to the one suggested.
Also notice that in the .solutions directory of the tarball you will find correct input files. Please only look at
these files after you have tried to solve the problems yourself.
11.5.4
Introduction
So far we always used PLUMED to run one simulation at a time. However, PLUMED can also be used in multireplica algorithms. When coupled with GROMACS (at least) it is also possible to run replica exchange simulations,
where coordinates are swapped from time to time. In this case, PLUMED is going to take into account the different
bias potentials applied to different replicas so as to compute correctly the acceptance.
Similarly to what we did before, we will first use the driver to understand how to prepare multi-replica input files.
However, the very same holds when you run multi-replica MD simulations with MD codes that support them. For
instance, in GROMACS that would be using the -multi option of mdrun.
Notice that this tutorial was tested using a pre-release version of PLUMED 2.4. In particular, we will use a special
syntax for multi-replica input that is only available starting with PLUMED 2.4.
Generated by Doxygen
714
Tutorials
11.5.5
Multi replica input files
Imagine that you are in a directory with these files
traj.0.xtc
traj.1.xtc
traj.2.xtc
plumed.dat
That is: three trajectories and a PLUMED input files. Let's say that the content of plumed.dat is
BEGIN_PLUMED_FILE
d: DISTANCE ATOMS=1,2
PRINT ARG=d FILE=COLVAR
You can use the following command to process the three trajectories simultaneously:
mpirun -np 3 plumed driver --multi 3 --plumed plumed.dat --mf_xtc traj.xtc
This command will produce three COLVAR files, namely COLVAR.0, COLVAR.1, and COLVAR.2.
How does this work?
You are here running three replicas of the plumed executable. When PLUMED opens a file for writing it adds a a
suffix corresponding to the replica number. This is done for all the possible files written by PLUMED and allows you
to distinguish the output of different replicas redirecting it to different files.
Attention
This is true also for input files that are opened for reading. However, when PLUMED does not find the input
file with the replica suffix, it looks for the file without the suffix. That's why here it is sufficient to provide a
single plumed.dat file. If by mistake you include an additional plumed.0.dat file in the same directory,
PLUMED will use that file for replica 0 (and plumed.dat for replicas 1 and 2). To be precise, this is true for
all the files read by PLUMED, with the exception of PDB files where the suffix is never added.
The last comment implies that if you need to process your trajectories with different input files you might do it
creating files named plumed.0.dat, plumed.1.dat, and plumed.2.dat. This is correct, and this was the
only way to do multi-replica simulations with different input files up to PLUMED 2.3. However, in the following we
will see how to obtain the same effect with a new special command that has been introduced in PLUMED 2.4.
11.5.6
Using special syntax for multiple replicas
In many cases, we need to run multiple replicas with almost identical PLUMED files. These files might be prepared
with cut-and-paste, which is very error prone, or could be set up with some smart bash or python script. Additionally,
one can take advantage of the INCLUDE keyword so as to have a shared input file with common definitions and
specific input files with replica-dependent keywords. However, as of PLUMED 2.4, we introduced a simpler manner
to manipulate multiple replica inputs with tiny differences. Look at the following example:
BEGIN_PLUMED_FILE
# Compute a distance
d: DISTANCE ATOMS=1,2
# Apply a restraint.
RESTRAINT ARG=d AT=@replicas:1.0,1.1,1.2 KAPPA=1.0
# On replica 0, this means:
#
RESTRAINT ARG=d AT=1.0 KAPPA=1.0
# On replica 1, this means:
#
RESTRAINT ARG=d AT=1.1 KAPPA=1.0
# On replica 2, this means:
#
RESTRAINT ARG=d AT=1.2 KAPPA=1.0
Generated by Doxygen
11.5 Trieste tutorial: Running and analyzing multi-replica simulations.
715
If you prepare a single plumed.dat file like this one and feeds it to PLUMED while using 3 replicas, the 3 replicas
will see the very same input except for the AT keyword, that sets the position of the restraint. Replica 0 will see a
restraint centered at 1.0, replica 1 centered at 1.1, and replica 2 centered at 1.2.
The @replicas: keyword is not special for RESTRAINT or for the AT keyword. Any keyword in PLUMED can
accept that syntax. For instance, the following single input file can be used to setup a bias exchange metadynamics
[96] simulations:
BEGIN_PLUMED_FILE
# Compute distance between atoms 1 and 2
d: DISTANCE ATOMS=1,2
# Compute a torsional angle
t: TORSION ATOMS=30,31,32,33
# Metadynamics.
METAD ...
ARG=@replicas:d,t
HEIGHT=1.0
PACE=100
SIGMA=@replicas:0.1,0.3
GRID_MIN=@replicas:0.0,-pi
GRID_MAX=@replicas:2.0,+pi
...
# On replica 0, this means:
# METAD ARG=d HEIGHT=1.0 PACE=100 SIGMA=0.1 GRID_MIN=0.0 GRID_MAX=2.0
# On replica 1, this means:
# METAD ARG=t HEIGHT=1.0 PACE=100 SIGMA=0.3 GRID_MIN=-pi GRID_MAX=+pi
This would be a typical setup for a bias exchange simulation. Notice that even though variables d and t are both
read in both replicas, d is only computed on replica 0 (and t is only computed on replica 1). This is because
variables that are defined but not used are never actually calculated by PLUMED.
If the value that should be provided for each replica is a vector, you should use curly braces as delimiters. For
instance, if the restraint acts on two variables, you can use the following input:
BEGIN_PLUMED_FILE
# Compute distance between atoms 1 and 2
d: DISTANCE ATOMS=10,20
# Compute a torsional angle
t: TORSION ATOMS=30,31,32,33
# Apply a restraint:
RESTRAINT ...
ARG=d,t
AT=@replicas:{{1.0,2.0} {3.0,4.0} {5.0,6.0}}
KAPPA=1.0,3.0
...
# On replica 0 this means:
# RESTRAINT ARG=d AT=1.0,2.0 KAPPA=1.0,3.0
# On replica 1 this means:
# RESTRAINT ARG=d AT=3.0,4.0 KAPPA=1.0,3.0
# On replica 2 this means:
# RESTRAINT ARG=d AT=5.0,6.0 KAPPA=1.0,3.0
Notice the double curly braces. The outer ones are used by PLUMED to know there the argument of the AT keyword
ends, whereas the inner ones are used to group the values corresponding to each replica. Also notice that the last
example can be split in multiple lines exploiting the fact that within multi-line statements (enclosed by pairs of ...)
newlines are replaced with simple spaces:
BEGIN_PLUMED_FILE
d: DISTANCE ATOMS=10,20
t: TORSION ATOMS=30,31,32,33
RESTRAINT ...
ARG=d,t
Generated by Doxygen
716
Tutorials
# indentation is not required (this is not python!)
# but makes the input easier to read
AT=@replicas:{
{1.0,2.0}
{3.0,4.0}
{5.0,6.0}
}
KAPPA=1.0
...
In short, whenever there are keywords that should vary across replicas, you should set them using the
@replicas: keyword. As mentioned above, you can always use the old syntax with separate input file,
and this is recommended when the number of keywords that are different is large.
11.5.7
Exercise 1: Running multi-replica simulations
Write a plumed file that allows you to run a multi-replica simulation of alanine dipeptide where the following four
replicas are simulated:
• Two replicas with no bias potential.
• A replica with metadynamics on φ.
• A replica with metadynamics on ψ .
With PLUMED 2.3 you should use four plumed.dat files (named plumed.0.dat, plumed.1.dat, etc). In
this case, the first two replicas feel no potential, so you could just use empty files. For the third and fourth replica
you could recycle the files from Trieste tutorial: Metadynamics simulations with PLUMED.
However, we recommend you to take the occasion to make practice with the special replica syntax of PLUMED 2.4.
Use the following input file as a starting point
BEGIN_PLUMED_FILE
# load the pdb to better select torsions later
MOLINFO __FILL__
# Compute the backbone dihedral angle phi, defined by atoms C-N-CA-C
phi: TORSION ATOMS=__FILL__
# Compute the backbone dihedral angle psi, defined by atoms N-CA-C-N
psi: TORSION ATOMS=__FILL__
metad: METAD ...
# Activate well-tempered metadynamics
# Deposit a Gaussian every 500 time steps, with initial height equal
# to 1.2 kJoule/mol, biasfactor equal to 10.0
# Remember: replica 0 and 1: no bias
# replica 2, bias on phi
# replica 3, bias on psi
ARG=__FILL__
HEIGHT=__FILL__ # make sure that replicas 0 and 1 feel no potential!
PACE=500
BIASFACTOR=10.0
SIGMA=0.35
# Gaussians will be written to file and also stored on grid
FILE=HILLS GRID_MIN=-pi GRID_MAX=pi
...
# Print both collective variables and the value of the bias potential on COLVAR file
PRINT ARG=__FILL__ FILE=COLVAR STRIDE=10
Now check the resources provided with this tutorial. There are 4 tpr files available (topol0.tpr, topol1.←tpr, topol2.tpr, and topol3.tpr). You can run a replica exchange simulation with gromacs using the
following command
Generated by Doxygen
11.5 Trieste tutorial: Running and analyzing multi-replica simulations.
717
> mpirun -np 4 gmx_mpi mdrun -plumed plumed.dat -nsteps 1000000 -replex 120 -multi 4
Notice that coordinates swaps will be attempted between different replicas every 120 steps. When computing the
acceptance, gromacs will take into account that different replicas might be subject to different bias potential. In this
example, replicas 0 and 1 are actually subject to the same potential, so all the exchanges will be accepted. You can
verify this using the command
> grep "Repl ex" md0.log
It is interesting to see what happens at different stages of the simulation. At the beginning of the trajectory you
should see something like this
> grep "Repl ex" md0.log | head
Repl ex 0 x 1
2 x 3
Repl ex 0
1 x 2
3
Repl ex 0 x 1
2 x 3
Repl ex 0
1 x 2
3
Repl ex 0 x 1
2 x 3
Repl ex 0
1
2
3
Repl ex 0 x 1
2 x 3
Repl ex 0
1 x 2
3
Repl ex 0 x 1
2 x 3
Repl ex 0
1 x 2
3
Notice that all the exchanges between replicas 0 and 1 are accepted and also almost all the exchanges between
replicas 1, 2, and 3. At a later stage you will more likely find something like this
> grep "Repl ex" md0.log | tail
Repl ex 0
1 x 2
3
Repl ex 0 x 1
2
3
Repl ex 0
1 x 2
3
Repl ex 0 x 1
2
3
Repl ex 0
1 x 2
3
Repl ex 0 x 1
2 x 3
Repl ex 0
1 x 2
3
Repl ex 0 x 1
2 x 3
Repl ex 0
1
2
3
Repl ex 0 x 1
2
3
Notice that all the exchanges between replicas 0 and 1 are still accepted. This is because the potential energy felt
by replicas 0 and 1 are identical. However, exchanges between replicas 1, 2, and 3 are sometime rejected.
Note
The setup above is very close to the one used in bias exchange simulations. However, in bias exchange simulations usually one would use at most one neutral (non-biased) replica. In addition, the
RANDOM_EXCHANGES command is often used.
11.5.8
Exercise 2: Analyzing a multiple-restraint simulation
In the following we will analyze the result of the simulation above. To this aim we will have to use the WHAM method.
The WHAM procedure described here is binless and allows one to reweight arbitrary bias potentials without the need
to discretize collective variables. As a first step it is necessary to create a concatenated trajectory that includes all
the conformations that you produced during your simulations.
> gmx_mpi trjcat -f traj_comp*.xtc -cat -o fulltraj.xtc
Generated by Doxygen
718
Tutorials
Notice that a new trajectory file fulltraj.xtc will be in your working directory now, approximately four times
bigger than the individual files traj_comp∗.xtc.
Now we will process that directory computing the bias potentials associated with the replicas that we simulated. Similarly to what we did in Trieste tutorial: Metadynamics simulations with PLUMED, we will assume that reweighting is
done with final bias potential [48]. Notice that also here it would be possible to use [3] instead.
BEGIN_PLUMED_FILE
# this will be file plumed_reweight.dat
# include here exactly the same file you used to run the simulation
# however, you should make some change to METAD:
# - replace PACE with a huge number
# - add TEMP=300 to set the temperature of the simulation
# (normally this is inherited from the MD code, but driver has no idea about it)
# - add RESTART=YES to trigger restart
__FILL__
__FILL__
__FILL__
__FILL__
# you should also change the PRINT command so as not to overwrite
# the files you wrote before.
# here omit STRIDE, so that you will print
# for all the frames in your concatenated trajectory
PRINT ARG=phi,psi FILE=COLVAR_CONCAT
# Then write the bias potential (as we did for reweighting)
# As a good practice, remember that there might be multiple bias
# potential applied (e.g. METAD and a RESTRAINT).
# to be sure that you include all of them, just combine them:
bias: COMBINE ARG=*.bias PERIODIC=NO
# here omit STRIDE, so that you will print the bias
# for all the frames in your concatenated trajectory
PRINT FILE=COLVAR_WHAM ARG=bias
Then analyze the concatenated trajectory with this command
> mpirun -np 4 plumed driver --mf_xtc fulltraj.xtc --plumed plumed_reweight.dat --multi 4
Notice that since fulltraj.xtc the four concurrent copies of PLUMED will all analyze the same trajectory,
which is what we want to do now. The result will be a number of COLVAR_WHAM files, one per replica, with a
number of lines corresponding to the whole concatenated trajectory.
# put the bias columns in a single file ALLBIAS
> paste COLVAR_WHAM.* | grep -v \# | awk ’{for(i=1;i<=NF/2;i++) printf($(i*2)"
");printf("\n");}’ > ALLBIAS
Have a look at ALLBIAS. It should look more or less like this
0.000000
0.000000
0.000000
0.000000
0.000000
0.000000
0.000000
0.000000
0.000000
0.000000
0.000000
0.000000
75.453800
74.973726
66.948910
70.383309
65.595489
67.689166
68.172206
68.143015
56.295899
60.164381
61.754951
60.869430
The first two columns correspond to the bias felt in replicas 0 and 1, that are unbiased, and thus should be zero.
In the other replicas on the other hand we will have large potentials accumulated by metadynamics. The actual
numbers might very depending on the length of your simulation.
Now you can use the provided python script to analyze the ALLBIAS file. SCRIPTS/wham.py should be provided three arguments: name of the file with bias potentials, number of replicas (that is the number of columns) and
value of k B T (2.5 in kj/mol).
Generated by Doxygen
11.5 Trieste tutorial: Running and analyzing multi-replica simulations.
719
# use the python script to compute weights
> python3 SCRIPTS/wham.py ALLBIAS 4 2.5
This will generate a file named weights.dat that contains the weights for each of the frame. The initial values
reported in the file should be similar to these ones:
> head weights.dat
3.688530731178e-05
3.899877363004e-05
7.861996862568e-07
3.663355487180e-06
1.647251040152e-06
2.689614526429e-06
3.254124396415e-06
1.511057459698e-05
2.342149322226e-05
5.032261109943e-06
Weights are very small since we have a long trajectory with many frames. You can check that they are normalized
using the command ‘awk ’{a+=$1}END{print a}' weights.dat`.
Now have a look at the weights. Remember that we are concatenating trajectories.
Can you understand why weights in the first half are systematically different from weights in the second half?
The first part correspond to the unbiased trajectories. All the snapshots sampled here are reasonably correct.
However, in the second part we have heavily biased snapshots, which also sample transition states. Those points
are assigned a low weight by WHAM so that they would be discarded in the calculation of any unbiased average.
Now we have the weight for each frame. We would like to compute the relative stability of the two free-energy wells
that correspond roughly to positive and negative φ.
> paste <(grep -v \# COLVAR_CONCAT.0) weights.dat | awk ’{if($2>0)wb+=$NF; else wa+=$NF}END{print wa,wb}’
This will tell you the unbiased population of the two minima. You should expect values close to these ones
0.968885 0.0311148
that tells you that the first minimum has a population of roughly 97%.
Note
This approach can be used to reweight any replica exchange simulation, irrespective of how different were
the employed bias potentials. This includes bias-exchange metadynamics [96] when using well-tempered
metadynamics [47]. Notice that for non-well-tempered bias exchange metadynamics one can use a very
similar approach based on binning that is described in [100]. In addition, the approach illustrated here can
be used directly in bias-exchange metadynamics simulations with additional restraints which are different in
different replicas (as in [101]) as well as other flavors of biased replica exchange simulations (e.g. [102]
[51]). With some modification to take into account the force field energy it can be used to analyze parallel
tempering simulations [103] and simulated tempering simulations [104] (notice that they can be implemented
with PLUMED + GROMACS using [105]).
Generated by Doxygen
720
Tutorials
11.5.9
Exercise 3: What if a variable is missing?
Repeat the exercise above (that is: running replica exchange MD simulation and analyze the result) but using only
three replicas:
• two unbiased replicas.
• one biased replica along psi.
Create a file plumed3.dat aimed at this. If you are not able you can find a working one in the solutions
directory. Then use the following commands similarly to before:
>
>
>
>
>
mpirun -np 3 gmx_mpi mdrun -plumed plumed3.dat -nsteps 1000000 -replex 120 -multi 3
gmx_mpi trjcat -f traj_comp{0,1,2}.xtc -cat -o fulltraj.xtc
mpirun -np 3 plumed driver --mf_xtc fulltraj.xtc --plumed plumed3_reweight.dat --multi 3
paste COLVAR_WHAM.{0,1,2} | grep -v \# | awk ’{for(i=1;i<=NF/2;i++) printf($(i*2)" ");printf("\n");}’ > ALL
python3 SCRIPTS/wham.py ALLBIAS 3 2.5
Compute as before the relative population of the two minima.
> paste <(grep -v \# COLVAR_CONCAT.0) weights.dat | awk ’{if($2>0)wb+=$NF; else wa+=$NF}END{print wa,wb}’
Which is the result? What can you learn from this example?
If you did things correctly, here you should find a population close to 2/3 for the first minimum and 1/3 for the second
one. Notice that this population just reflects the way we initialized the simulations (2 of them in one minimum and
1 in the other minimum) and does not take into account which is the relative stability of the two minima according
to the real potential energy function. In other words, we are just obtaining the relative population that we used to
initialize the simulation.
Also plot the colvar files and look at them with attention. An excerpt is shown below.
always due to accepted exchanges between replicas."
How many transitions between the two free-energy wells can you observe? Remember that replica exchange
involves coordinate swaps that do not correspond to the real system dynamics. It is very useful to look at "demuxed"
trajectories.
11.5.10
Exercise 4: "demuxing" your trajectories
Use the following commands
> demux.pl md0.log
This will produce two files: replica_index.xvg and replica_temp.xvg. The former allows to convert
your trajectories to continuous ones with the following commands
> demux.pl md0.log
> gmx_mpi trjcat -f traj_comp?.xtc -demux replica_index.xvg
You will now find new trajectories 0_trajout.xtc, 1_trajout.xtc, 2_trajout.xtc, and 3_←trajout.xtc. These files can be in turn analyzed with plumed driver. Try to recompute collective
variables on the trajectories obtained in Exercise 1: Running multi-replica simulations and with those obtained in
Exercise 3: What if a variable is missing?.
As you can see, the trajectories from Exercise 1: Running multi-replica simulations show a number of transitions.
On the other hand, the trajectories from Exercise 3: What if a variable is missing? are stuck.
As a general rule, notice that there is no way to estimate correctly the relative population of two metastable states if
there is not a continuous "demuxed" trajectory joining them, possibly exhibiting multiple transitions.
Generated by Doxygen
11.6 Trieste tutorial: Real-life applications with complex CVs
11.5.11
721
Conclusions
In summary, in this tutorial you should have learned how to use PLUMED to:
• Run multi replica simulations.
• Analyze them using WHAM.
Notice that the setup used is similar to the ones typically used in bias exchange simulations but can be easily
adapted to any case where multiple replicas should be combined that feel different bias potentials. Moreover, the
problematic example discussed shows that one should be careful and check if real transitions are observed during
a replica exchange simulation.
11.6
Trieste tutorial: Real-life applications with complex CVs
11.6.1
Aims
The aim of this tutorial is to train users to learn the syntax of complex collective variables and use them to analyze
MD trajectories of realistic biological systems and bias them with metadynamics.
11.6.2
Objectives
Once this tutorial is completed students will be able to:
• Write the PLUMED input file to use complex CVs for analysis
• Analyze trajectories and calculate the free energy of complex biological systems
- Perform error analysis and evaluate convergence in realistic situations
• Setup, run, and analyze metadynamics simulations of a complex system
11.6.3
Resources
The reference trajectories and input files for the exercises proposed in this tutorial can be downloaded from github
using the following command:
wget https://github.com/plumed/trieste2017/raw/master/tutorial/data/tutorial_6.tgz
This tutorial has been tested on a pre-release version of version 2.4. However, it should not take advantage of
2.4-only features, thus should also work with version 2.3.
11.6.4
Introduction
In this tutorial we propose exercises on the following biological systems:
• the BRCA1-associated RING domain protein 1 (BARD1 complex)
• the cmyc peptide in presence of urea at low concentration (cmyc-urea)
• the protein G B1 domain
The exercise are of increasing difficulties, inputs are partially provided for the first and second cases while for
the last one the user is expected to be autonomous.
Generated by Doxygen
722
Tutorials
11.6.5
Exercise 1: analysis of the BARD1 complex simulation
The BARD1 complex is a hetero-dimer composed by two domains of 112 and 117 residues each. The system is
represented at coarse-grained level using the MARTINI force field.
In the TARBALL of this exercise, we provide a long MD simulation of the BARD1 complex in which the two domains
explore multiple different conformations.
Note
We encourage the users to get familiar with the system by visualizing the MD trajectory using VMD.
The users are expected to:
• calculate the values of different CVs on the trajectory
• estimate the free energies as a function of the CVs tested (mono- and multi-dimensional)
• extracting from the trajectories the configurations corresponding to relevant free-energy minima
• calculate the error in the associated free energy using the block analysis technique
• evaluate the convergence of the original trajectory
The users are free to choose his/her favorite CVs and they are encouraged to use the on-line manual to create their
own PLUMED input file. However, we encourage all the users to experiment at least with the following CVs:
1) RMSD and/or DRMSD from the native state
The following line can be added to the plumed.dat file to calculate the RMSD on the beads representing the
backbone amino acids:
BEGIN_PLUMED_FILE
rmsd: RMSD REFERENCE=bard1_rmsd.pdb TYPE=OPTIMAL
while this one can be used to calculate the DRMSD between chains:
BEGIN_PLUMED_FILE
drmsd: DRMSD REFERENCE=bard1_drmsd.pdb TYPE=INTER-DRMSD LOWER_CUTOFF=0.1 UPPER_CUTOFF=1.5
2) Number of inter-chains contacts (specific, i.e. native, or all).
This can be achieved with the COORDINATION CVs, as follows:
BEGIN_PLUMED_FILE
# backbone beads index for chain A
chainA: GROUP ATOMS=1,3,5,7,9,10,12,15,17,19,21,23,25,27,29,31,33,34,36,38,41,43,45,47,49,51,53,55,57,59,61,63
# backbone beads index for chain B
chainB: GROUP ATOMS=226,228,230,232,234,235,238,239,240,245,246,250,252,255,256,257,259,261,264,266,268,271,27
coord: COORDINATION GROUPA=chainA GROUPB=chainB NOPBC R_0=1.0
3) A CV describing the relative orientation of the two chains.
This can be achieved, for example, by defining suitable virtual atoms with the CENTER keyword and the TORSION
CV:
BEGIN_PLUMED_FILE
# virtual atom representing the first half of chain A
chainA_1: CENTER ATOMS=__FILL__
# virtual atom representing the second half of chain A
chainA_2: CENTER ATOMS=__FILL__
# virtual
chainB_1:
# virtual
chainB_2:
atom representing the first half of chain B
CENTER ATOMS=__FILL__
atom representing the second half of chain B
CENTER ATOMS=__FILL__
# torsion CV
dih: TORSION ATOMS=__FILL__
Generated by Doxygen
11.6 Trieste tutorial: Real-life applications with complex CVs
11.6.6
723
Exercise 2: analysis of the cmyc-urea simulation
Cmyc is a small disordered peptide made of 11 amino acid. In solution, cmyc adopts a variety of different, but
equally populated conformations. In the TARBALL of this exercise, we provide a long MD simulation of cmyc in
presence of a single molecule of urea.
Note
We encourage the users to get familiar with the system by visualizing the MD trajectory using VMD.
The users are expected to:
• characterize the conformational ensemble of cmyc by calculating free-energies as a function of different CVs.
• calculate the fraction of bound and unbound molecules of urea by defining suitable CVs to measure the
position of urea relative to cmyc.
• find the cmyc amino acids that bind urea the most and the least.
• calculate the ensemble averages of different experimental CVs.
Warning
Be careful that the original trajectory might be broken by PBC!
The users are free to choose his/her favorite CVs and they are encouraged to use the on-line manual to create
their own PLUMED input file. However, we encourage all the users to experiment at least with the following CVs to
characterize the conformational landscape of cmyc:
1) the radius of gyration of cmyc (GYRATION)
2) the content of alpha (ALPHARMSD) and beta (ANTIBETARMSD) secondary structure
The fraction of bound and unbound molecules of urea can be computed after evaluating the minimum distance
among all the distances between heavy atoms of cmyc and urea, as follows:
BEGIN_PLUMED_FILE
# cmyc heavy atoms
cmyc: GROUP ATOMS=5,6,7,9,11,14,15,17,19,22,24,26,27,28,30,32,34,38,41,45,46,47,49,51,54,56,60,64,65,66,68,70,
# urea heavy atoms
urea: GROUP ATOMS=192,193,194,197
# minimum distance cmyc-urea
mindist: DISTANCES GROUPA=cmyc GROUPB=urea MIN={BETA=50.}
For estimating the cmyc amino acid that bind the most and the least urea, we leave the users the choice of the best
strategy.
For the calculation of ensemble averages of experimental CVs, we suggest to use:
1) 3J scalar couplings (JCOUPLING)
2) the FRET intensity between termini (FRET)
and we encourage the users to look at the examples provided in the manual for the exact syntax.
Generated by Doxygen
724
Tutorials
11.6.7
Exercise 3: Protein G folding simulations
GB1 is a small protein domain with a simple beta-alpha-beta fold. It is a well studied protein that folds on the
millisecond time scale. Here we use a structure based potential and well-tempered metadynamics to study the free
energy of folding and unfolding. In the TARBALL of this exercise we provide the files needed to run the simulation,
the user should write the plumed input file needed to bias the sampling.
The users are expected to:
• setup and perform a well-tempered metadynamics simulation
• evaluate convergence and error calculation of the metadynamics simulation
• calculate the free energy difference between the folded and unfolded state of this protein
• evaluate the robustness of the former by reweighting the resulting free energy as function of different CVs
The users are free to choose his/her favorite CVs and they are encouraged to use the on-line manual to create
their own PLUMED input file. However, we encourage all the users to experiment at least with the following CVs to
characterize the free-energy landscape of GB1:
• RMSD with respect to the folded state
• GYRATION
• ALPHABETA
• DIHCOR
The users should select two of them for the METAD simulation. Once you are satisfied by the convergence of your
simulation, you can use one of the reweighting algorithms proposed to evaluate the free-energy difference between
folded and unfolded state as a function of multiple collective variables.
BEGIN_PLUMED_FILE
#this allows you to use short-cut for dihedral angles
MOLINFO STRUCTURE=GB1_native.pdb
#add here the collective variables you want to bias
#add here the METAD bias, remember that you need to set: one SIGMA per CV, one single HEIGHT, one BIASFACTOR a
#Using GRIDS can increase the performances, so set a as many GRID_MIN and GRID_MAX as the number of CVs with r
#(i.e an RMSD will range between 0 and 3, while ALPHABETA and DIHCOR will range between 0 and N of dihedrals).
#add here the printing
11.6.8
Conclusions
In summary, in this tutorial you should have learned how to use PLUMED to:
• Analyze trajectories of realistic biological systems using complex CVs
• Extract conformations that correspond to local free-energy minima
• Apply block analysis to estimate error in the reconstructed free-energy profiles
• Calculate ensemble averages of experimental CVs
• Reweight well-tempered metadynamics simulations
Generated by Doxygen
11.7 Belfast tutorial: Analyzing CVs
11.7
Belfast tutorial: Analyzing CVs
11.7.1
Aims
725
The aim of this tutorial is to introduce the users to the plumed syntax. We will go through the writing of simple
collective variable and we will use them to analyze a trajectory in terms of probability distributions and free energy.
11.7.2
Learning Outcomes
Once this tutorial is completed students will:
• Know how to write a simple plumed input file
• Know how to analyze a trajectory using plumed
11.7.3
Resources
The tarball for this project contains the following files:
• trajectory-short.xyz : a (short) trajectory for a 16 residue protein in xyz format. All calculations with plumed
driver use this trajectory.
• template.pdb : a single frame from the trajectory that can be used in conjunction with the MOLINFO command
11.7.4
Instructions
PLUMED2 is a library that can be accessed by multiple codes adding a relatively simple and well documented
interface. Once PLUMED is installed you can run a plumed executable that can be used for multiple purposes:
plumed --help
some of the listed options report about the plumed available functionalities, other can be used to tell plumed to do
something: from analyzing a trajectory to patch the source code of a MD code and so on. All the commands have
further options that can be seen using plumed command –help, i.e.:
plumed driver --help
In the following we are going to see how to write an input file for plumed2 that can be used to analyze a trajectory.
11.7.4.1
A note on units
By default the PLUMED inputs and outputs quantities in the following units:
• Energy - kJ/mol
• Length - nanometers
• Time - picoseconds
If you want to change these units you can do this using the UNITS keyword.
Generated by Doxygen
726
11.7.4.2
Tutorials
Introduction to the PLUMED input file
A typical input file for PLUMED input is composed by specification of one or more CVs, the printout frequency and
a termination line. Comments are denoted with a # and the termination of the input for PLUMED is marked with
the keyword ENDPLUMED. Whatever it follows is ignored by PLUMED. You can introduce blank lines. They are not
interpreted by PLUMED.
In the following input we will analyze the DISTANCE between the two terminal carbons of a 16 residues peptide,
and we will PRINT the results in file named COLVAR.
#my first plumed input:
DISTANCE ATOMS=2,253 LABEL=e2edist
#printout frequency
PRINT ARG=e2edist STRIDE=1 FILE=COLVAR
#endofinput
ENDPLUMED
here I can write what I want it won’t be read.
Now we can use this simple input file to analyze the trajectory included in the RESOURCES:
plumed driver --plumed plumed.dat --ixyz trajectory-short.xyz --length-units 0.1
NOTE: –length-units 0.1, xyz files, as well as pdb files, are in Angstrom.
You should have a file COLVAR, if you look at it (i.e. more COLVAR) the first two lines should be:
#! FIELDS time e2edist
0.000000 2.5613161
NOTE: the first line of the file COLVAR tells you what is the content of each column.
In PLUMED2 the commands defined in the input files are executed in the same order in which they are written, this
means that the following input file is wrong:
#printout frequency
PRINT ARG=e2edist STRIDE=1 FILE=COLVAR
#my first plumed input:
DISTANCE ATOMS=2,253 LABEL=e2edist
#endofinput
ENDPLUMED
here I can write what I want it won’t be read.
Try to run it.
Sometimes, when calculating a collective variable, you may not want to use the positions of a number of atoms directly. Instead you may wish to use the position of a virtual atom whose position is generated based on the positions
of a collection of other atoms. For example you might want to use the center of a group of atoms (CENTER):
Since PLUMED executes the input in order you need to define the new Virtual Atom before using it:
Generated by Doxygen
11.7 Belfast tutorial: Analyzing CVs
727
first: CENTER ATOMS=1,2,3,4,5,6
last: CENTER ATOMS=251-256
e2edist: DISTANCE ATOMS=2,253
comdist: DISTANCE ATOMS=first,last
PRINT ARG=e2edist,comdist STRIDE=1 FILE=COLVAR
ENDPLUMED
NOTE: an action (i.e. CENTER or DISTANCE here) can be either labeled using LABEL as we did before or as
label: ACTION as we have just done here.
With the above input this is what happen inside PLUMED with a STRIDE=1:
1. calculates the position of the Virtual Atom 'first' as the CENTER of atoms from 1 to 6;
2. calculates the position of the Virtual Atom 'last' as the CENTER of atoms from 251 to 256;
3. calculates the distance between atoms 2 and 253 and saves it in 'e2edist';
4. calculates the distance between the two atoms 'first' and 'last' and saves it in 'comdist';
5. print the content of 'e2edist' and 'comdist' in the file COLVAR
In the above input we have used two different ways of writing the atoms used in CENTER calculation:
1. ATOMS=1,2,3,4,5,6 is the explicit list of the atoms we need
2. ATOMS=251-256 is the range of atoms needed
ranges of atoms can be defined with a stride which can also be negative:
1. ATOMS=from,to:by (i.e.: 251-256:2)
2. ATOMS=to,from:-by (i.e.: 256-251:-2)
Now by plotting the content of the COLVAR file we can compare the behavior in this trajectory of both the terminal
carbons as well as of the center of masses of the terminal residues.
gnuplot
What do you expect to see now by looking at the trajectory? Let's have a look at it
vmd template.pdb trajectory-short.xyz
Virtual atoms can be used in place of standard atoms everywhere an atom can be given as input, they can also be
used together with standard atoms. So for example we can analyze the TORSION angle for a set of Virtual and
Standard atoms:
first: CENTER ATOMS=1-6
last: CENTER ATOMS=251-256
cvtor: TORSION ATOMS=first,102,138,last
PRINT ARG=cvtor STRIDE=1 FILE=COLVAR
ENDPLUMED
Generated by Doxygen
728
Tutorials
The above CV don't look smart to learn something about the system we are looking at. In principle CV are used to
reduce the complexity of a system by looking at a small number of properties that could be enough to rationalize its
behavior.
Now try to write a collective variable that measures the Radius of Gyration of the system: GYRATION.
NOTE: if what you need for one or more variables is a long list of atoms and not a virtual atom one can use the
keyword GROUP. A GROUP can be defined using ATOMS in the same way we saw before, in addition it is also
possible to define a GROUP by reading a GROMACS index file.
ca: GROUP ATOMS=9,16,31,55,69,90,102,114,124,138,160,174,194,208,224,238
Now 'ca' is not a virtual atom but a simple list of atoms.
11.7.4.3
MULTICOLVAR
Sometimes it can be useful to calculate properties of many similar collective variables at the same time, for example
one can be interested in calculating the properties of the distances between a group of atoms, or properties linked
to the distribution of the dihedral angles of a chain and so on. In PLUMED2 this kind of collective variables fall under
the name of MULTICOLVAR (cf. MultiColvar.) Here we are going to analyze the distances between CA carbons
along the chain:
ca: GROUP ATOMS=9,16,31,55,69,90,102,114,124,138,160,174,194,208,224,238
dd: DISTANCES GROUP=ca MEAN MIN={BETA=50} MAX={BETA=0.02} MOMENTS=2
PRINT ARG=dd.mean,dd.min,dd.max,dd.moment-2 STRIDE=1 FILE=COLVAR
ENDPLUMED
The above input tells PLUMED to calculate all the distances between CA carbons and then look for the mean
distance, the minimum distance, the maximum distance and the variance. In this way we have defined four collective
variables that are calculated using the distances. These four collective variables are stored as components of the
defined action 'dd': dd.mean, dd.min, dd.max, dd.moment-2.
The infrastructure of multicolvar has been used to develop many PLUMED2 collective variables as for example the
set of Secondary Structure CVs (ANTIBETARMSD, PARABETARMSD and ALPHARMSD).
MOLINFO STRUCTURE=template.pdb
abeta: ANTIBETARMSD RESIDUES=all TYPE=DRMSD LESS_THAN={RATIONAL R_0=0.08 NN=8 MM=12} STRANDS_CUTOFF=1
PRINT ARG=abeta.lessthan STRIDE=1 FILE=COLVAR
ENDPLUMED
We have now seen how to write the input some of the many CVs available in PLUMED. More complex CVs will be
discussed in the next workshop, Belfast tutorial: Adaptive variables I.
Generated by Doxygen
11.7 Belfast tutorial: Analyzing CVs
11.7.4.4
729
Analysis of Collective Variables
Collective variables are usually used to visualize the Free Energy of a system. Given a system evolving at fixed
temperature, fixed number of particles and fixed volume, it will explore different conformations with a probability
P (q) ∝ e
U (q)
BT
− kb
where q are the microscopic coordinates and kB is the Boltzmann constant.
It is possible to analyze the above probability as a function of one or more collective variable s(q):
Z
P (s) ∝
U (q)
BT
− kb
dqe
δ(s − s(q))
where the δ function means that to for a given value s of the collective variable are counted only those conformations
for which the CV is s. The probability can be recast to a free energy by taking its logarithm:
F (s) = −kB T log P (s)
This means that by estimating the probability distribution of a CV it is possible to know the free energy of a system
along that CV. Estimating the probability distribution of the conformations of a system is what is called 'sampling'.
In order to estimate a probability distribution one needs to make HISTOGRAM from the calculated CVs. PLUMED2
includes the possibility of constructing a histogram from data both on the fly as well as a posteriori as we are going
to do now.
MOLINFO STRUCTURE=template.pdb
abeta: ANTIBETARMSD RESIDUES=all TYPE=DRMSD LESS_THAN={RATIONAL R_0=0.08 NN=8 MM=12} STRANDS_CUTOFF=1
ca: GROUP ATOMS=9,16,31,55,69,90,102,114,124,138,160,174,194,208,224,238
DISTANCES ...
GROUP=ca MEAN MIN={BETA=50} MAX={BETA=0.02} MOMENTS=2 LABEL=dd
... DISTANCES
PRINT ARG=abeta.lessthan,dd.mean,dd.min,dd.max,dd.moment-2 STRIDE=1 FILE=COLVAR
HISTOGRAM ...
ARG=abeta.lessthan,dd.mean
LABEL=hh
KERNEL=DISCRETE
GRID_MIN=0,0.8
GRID_MAX=4,1.2
GRID_BIN=40,40
... HISTOGRAM
DUMPGRID GRID=hh FILE=histo
ENDPLUMED
NOTE: HISTOGRAM ... means that what follow is part of the HISTOGRAM function, the same can be done for any
action in PLUMED.
The above input tells PLUMED to accumulate the two collective variables on a GRID. In addition the probability
can be converted to a free-energy using the CONVERT_TO_FES method and then use DUMPGRID to write it.
Histograms can be accumulated in a smoother way by using a KERNEL function, a kernel is a normalized function,
for example a normalized gaussian is the default kernel in PLUMED, that is added to the histogram centered in the
position of the data. Estimating a probability density using kernels can in principle give more accurate results, on
the other hand in addition to the choice of the binning one has to choose a parameter that is the WIDTH of the
kernel function. As a rule of thumb: the grid spacing should be smaller (i.e. one half or less) than the BANDWIDTH
and the BANDWIDTH should be smaller (i.e. one order of magnitude) than the variance observed/expected for the
variable.
Generated by Doxygen
730
Tutorials
HISTOGRAM ...
LABEL=hh
ARG=abeta.lessthan,dd.mean
GRID_MIN=0,0.8
GRID_MAX=4,1.2
GRID_SPACING=0.04,0.004
BANDWIDTH=0.08,0.008
... HISTOGRAM
DUMPGRID GRID=hh FILE=histo
ENDPLUMED
If you have time less at the end of the session read the manual and look for alternative collective variables to
analyze the trajectory. Furthermore try to play with the HISTOGRAM parameters to see the effect of using KERNEL
in analyzing data.
11.8
Belfast tutorial: Adaptive variables I
11.8.1
Aim
In this section we want to introduce the concept of adaptive collective variables. These are special variables that
are knowledge-based in that are built from a pre-existing notion of the mechanism of the transition under study.
11.8.2
Resources
Here is the tarball with the files referenced in the following.
11.8.3
What happens when in a complex reaction?
When you deal with a complex conformational transition that you want to analyze (or bias), very often you cannot
just describe it with a single order parameter.
As an example in Figure belfast-2-cdk-fig I consider a large conformational transition like those involved in activating
the kinase via open-close transition of the activation loop. In sticks you see the part involved in the large conformational change, the rest is either keeping the structure and just moving a bit or is a badly resolved region in the
X-ray structure. This is a complex transition and it is hard to tell which is the order parameter that best describes
the transition.
One could identify a distance that can distinguish open from close but
• the plasticity of the loop is such that the same distance can correspond to an almost closed loop and almost
open loop. One would like to completely divide these two situations with something which is discriminating
what intuitively one would think as open and closed
• the transition state is an important point where one would like to see a certain crucial interaction forming/breaking so to better explain what is really happening. If you capture then hypothetically you would
be able to say what is dictating the rate of this conformational transition. A generic distance is a very hybrid
measure that is unlikely to capture a salt-bridge formation and a concerted change of many dihedral angles
or the change in solvation state that are happening while the transition is happening. All these things are
potentially important in such transition but none of them is explaining the whole thing.
So basically in these cases you have to deal with an intrinsic multidimensional collective variable where you
would need many dimensions. How would you visualize a 10 dimensional CV where you use many distances,
coordination numbers and dihedral angles (ouch, they're periodic too!) ?
Generated by Doxygen
11.8 Belfast tutorial: Adaptive variables I
731
Another typical case is the docking of a small molecule in a protein cleft or gorge, which is the mechanism of drug
action. This involves specific conformational transition from both the small molecule and the protein as the small
molecule approaches the protein cavity. This also might imply a specific change in the behavior when the solvation
state changes.
Other typical examples are chemical reactions. Nucleophillic attacks typically happen with a role from the solvent
(see some nice paper from Nobel-prize winner Arieh Warshel) and sizable geometric distortions of the neighboring
groups.
11.8.4
Path collective variables
One possibility to describe many different things that happen in a single reaction is to use a dimensional reduction
technique and in plumed the simplest example that may show its usefulness can be considered that of the path
collective variables.
In a nutshell, your reaction might be very complex and happening in many degree of freedom but intuitively is a sort
of track along which the reaction proceeds. So what we need is a coordinate that, given a conformation, just tells
which point along the "reactive track" is closest.
For example, in Fig. belfast-2-ab-fig, you see a typical chemical reaction (hydrolysis of methyl phosphate) with
the two end-points denoted by A and B. If you are given a third point, just by looking at it, you might find that this
resembles the reactant more than the product, so, hypothetically, if you would intuitively give a parameter that would
be 1 for a configuration in the A state and 2 for a configuration in the B state, you probably would give it something
like 1.3, right?
Path collective variables are the extension to this concept in the case you have many conformation that describe
your path, and therefore, instead of an index that goes from 1 to 2 you have an index that goes from 1 to N , where
N is the number of conformation that you use in input to describe your path.
From a mathematical point of view, that's rather simple. The progress along the path is calculated with the following
equation:
PN
S(X) = Pi=1
N
i exp−λ|X−Xi |
i=1
exp−λ|X−Xi |
where in belfast-2-s-eq the |X − Xi | represents a distance between one configuration X which is analyzed and
another from the set that compose the path Xi . The parameter λ is a positive value that is tuned in a way explained
later. here are a number of things to note to make you think that this is exactly what you want.
• The negative exponential function is something that is 1 whenever the value at the exponent is zero, and is
progressively smaller when the value is larger than zero (trivially, the case with the value at the exponent
larger than zero never occurs since lambda is a positive quantity and the distance is by definition positive).
• Whenever you sit exactly on a specific images Xj then all the other terms in the sum disappear (if λ is large
enough) and only the value j survives returning exactely S(X) = j .
In order to provide a value which is continuous, the parameter λ should be correctly tuned. As a rule of thumb I use
the following formula
2.3(N − 1)
λ = PN −1
i=1 |Xi − Xi+1 |
Generated by Doxygen
732
Tutorials
which imply that one should calculate the average distance between consecutive frames composing the path. Note
also that this distance should be more or less similar between the frames. Generally I tolerate fluctuation of the
order of 10/15 percent tops. If you have larger, then it is better to have a smaller value of λ.
It is important to note that in principle one could even have a specific λ value associated to each frame of the path
but this would provide some distortion in the diffusion coefficient which could potentially harm a straightforward
interpretation of the free energy landscape.
So, at this point it is better to understand what is meant with "distance" since a distance between two conformations
can be calculated in very many ways. The way we refer here is by using mean square deviation after optimal
alignment. This means that at each step in which the analysis is performed, a number N of optimal alignments is
performed. Namely what is calculated is |X − Xi | = d(X, Xi )2 where d(X, Xi ) is the RMSD as defined in what
you see here RMSD.
Using the MSD instead of RMSD is sometimes more convenient and more stable (you do not have a denominator
that goes to zero in the derivatives when biasing.
Anyway this is a matter of choice. Potentially one could equally employ other metrics like a set of coordination
numbers (this was done in the past), and then you would avoid the problem of rototranslations (well, which is not
a problem since you have it already in plumed) but for some applications that might become appealing. So in path
collective variables (and in all the dimensional reduction based collective variables) the problem is converted from
the side of choosing the collective variable in choosing the right way to calculate distances, also called "metrics".
The discussion of this issue is well beyond the topic of this tutorial, so we can move forward in how to tell plumed to
calculate the progress along the path whenever the MSD after optimal alignment is used as distance.
p1: PATHMSD REFERENCE=all.pdb LAMBDA=50.0
PRINT ARG=p1.sss,p1.zzz STRIDE=100 FILE=colvar FMT=%8.4f
Note that reference contains a set of PDB, appended one after the other, with a END field. Note that there is no
need to place all the atoms of the system in the PDB reference file you provide. Just put the atoms that you think
might be needed. You can leave out big domains, solvent and ions if you think that is not important for your use.
Additionally, note that the measure units of LAMBDA are in the units of the code. In gromacs they are in nm∧ 2
while NAMD is Angstrom∧ 2. PATHMSD produces two arguments that can be printed or used in other ActionWith←Arguments. One is the progress along the path of belfast-2-s-eq, the other is the distance from the closest point
along the path, which is denoted with the zzz component. This is defined as
N
X
1
exp−λ|X−Xi | )
Z(X) = − log(
λ
i=1
It is easy to understand that in case of perfect match of X = Xi this equation gives back the value of |X − Xi |
provided that the lambda is adjusted correctly.
So, the two variables, put together can be visualized as This variable is important because whenever your simulation
is running close to the path (low Z values), then you know that you are reproducing reliably the path you provided
in input but if by chance you find some other path that goes, say, from S = 1, Z = 0 to S = N, Z = 0 via large
Z values, then it might well be that you have just discovered a good alternative pathway. If your path indeed is
going from S = 1, Z = large to S = N, Z = large then it might well be that you do not have your reaction
accomplished, since your reaction, by definition should go from the reactant which is located at S = 1, Z = 0
to the product, which is located at S = 1, Z = N so you should pay attention. This case is exemplified in Fig.
belfast-2-ab-sz-nowhere-fig
Generated by Doxygen
11.8 Belfast tutorial: Adaptive variables I
11.8.5
733
A note on the path topology
A truly important point is that if you get a trajectory from some form of accelerated dynamics (e.g. simply by heating)
this cannot simply be converted into a path. Since it is likely that your trajectory is going back and forth randomly (not
in the case of SMD or US, discussed later), your trajectory might be not topologically suitable. To understand that,
suppose you simply collect a reactive trajectory of 100 ps into the reference path you give to the PATHMSD and
simply you assign the frame of 1 ps to index 1 (first frame occurring in the reference file provided to PATHMSD),
the frame of 2 ps to index 2 and so on : it might be that you have two points which are really similar but one is
associated to step, say 5 and the other is associated with frame 12. When you analyze the same trajectory, when
you are sitting on any of those points then the calculation of S will be an average like S(X) = (5 + 12)/2 = 8.5
which is an average of the two indexes and is completely misleading since it let you think that you are moving
between point 8 and 9, which is not the case. So this evidences that your reference frames should be "topologically
consecutive". This means that frame 1 should be the closest to frame 2 and all the other frames should be farther
apart. Similarly frame 2 should be equally close (in an RMSD sense) to 1 and 3 while all the others should be farther
apart. Same for frame 3: this should be closest to frame 2 and 4 and farther apart from all the others and so on.
This is equivalent to calculate an "RMSD matrix" which can be conveniently done in vmd (this is a good exercise for
a number of reasons) with RMSD Trajectory tools, by choosing different reference system along the set of reference
frames.
This is shown in Fig. belfast-2-good-matrix-fig where the matrix has a typical gull-wing shape.
On the contrary, whenever you extract the frames from a pdb that you produced via free MD or some biased
methods (SMD or Targeted MD for example) then your frame-to-frame distance is rather inhomogeneous and looks
something like
Aside from the general shape, which is important to keep the conformation-to-index relation (this, as we will see in
the next part is crucial in the multidimensional scaling) the crucial thing is the distance between neighbors.
As a matter of fact, this is not much important in the analysis but is truly crucial in the bias. When biasing a
simulation, you generally want to introduce a force that push your system somewhere. In particular, when you add
a bias which is based on a path collective variable, most likely you want that your system goes back and forth along
your path. The bias is generally applied by an additional term in the Hamiltonian, this can be a spring term for
Umbrella Sampling, a Gaussian function for Metadynamics or whatever term which is a function of the collective
variable s. Therefore the Hamiltonian H(X) where X is the point of in the phase space where your system is takes
the following form
H 0 (X) = H(X) + U (S(X))
where U (S(X)) is the force term which depends on the collective variable that ultimately is a function of the X .
Now, when you use biased dynamics you need to evolve according the forces that this term produces (this only
holds for MD, while not in MC) and therefore you need
Fi = −
dH 0 (X) ∂U (S(X)) ∂S(X)
dH 0 (X)
=−
−
dxi
dxi
∂S
∂xi
This underlines the fact that, whenever
the progress along the path is
∂S(X)
=
∂xi
PN
i=1
∂S(X)
∂xi
is zero, then you have no force on the system. Now the derivative of
i|
−λ i ∂|X−X
exp−λ|X−Xi | (
∂xi
−
PN
−λ|X−Xi |
i=1 exp
PN
i=1
PN
PN
∂|X−X |
∂|X−Xi |
i exp−λ|X−Xi | )( j=1 −λ ∂xi j exp−λ|X−Xj | )
i=1 −λ i
∂xi
=
PN
PN
−λ
exp
( i=1 exp−λ|X−Xi | )2
i=1
which can be rewritten as
∂S(X)
=λ
∂xi
PN
i=1
∂|X−Xi |
exp−λ|X−Xi | [s(X)
∂xi
PN
−λ|X−Xi |
i=1 exp
− i]
It is interesting to note that whenever the λ is too small the force will vanish. Additionally, when λ is too large, then it
one single exponential term will dominate over the other on a large part of phase space while the other will vanish.
This means that the S(X) will assume almost discrete values that produce zero force. Funny, isn't it?
Generated by Doxygen
734
11.8.6
Tutorials
How many frames do I need?
A very common question that comes is the following: "I have my reaction or a model of it. how many frames do I
need to properly define a path collective variable?" This is a very important point that requires a bit of thinking. It all
depends on the limiting scale in your reaction. For example, if in your process you have a torsion, as the smallest
event that you want to capture with path collective variable, then it is important that you mimic that torsion in the path
and that this does not contain simply the initial and final point but also some intermediate. Similarly, if you have a
concerted bond breaking, it might be that all takes place in the range of an Angstrom or so. In this case you should
have intermediate frames that cover the sub-Angstrom scale. If you have both in the same path, then the smallest
dominates and you have to mimic also the torsion with sub-Angstrom accuracy.
11.8.7
Some tricks of the trade: the neighbors list.
If it happens that you have a very complex and detailed path to use, say that it contains 100 frames with 200 atoms
each, then the calculation of a 100 alignment is required every time you need the CV. This can be quite expensive
but you can use a trick. If your trajectory is continuous and you are sure that your trajectory does not show jumps
where your system suddenly move from the reactant to the product, then you can use a so-called neighbor list. The
plumed input shown before then becomes
p1: PATHMSD REFERENCE=all.pdb LAMBDA=50.0 NEIGH_STRIDE=100 NEIGH_SIZE=10
PRINT ARG=p1.sss,p1.zzz STRIDE=100 FILE=colvar FMT=%8.4f
and in this case only the closest 10 frames from the path will be used for the CV. Then the list of the frames to use is
updated every 100 steps. If you are using a biased dynamics this may introduce sudden change in the derivatives,
therefore it is better to check the stability of the setup before running production-quality calculations.
11.8.8
The molecule of the day: alanine dipeptide
Here and probably in other parts of the tutorial a simple molecule is used as a test case. This is alanine dipeptide in
vacuum. This rather simple molecule is useful to make many benchmark that are around for data analysis and free
energy methods. It is a rather nice example since it presents two states separated by a high (free) energy barrier.
In Fig. belfast-2-ala-fig its structure is shown.
The two main metastable states are called C7 eq and C7 ax.
Here metastable states are intended as states which have a relatively low free energy compared to adjacent conformation. At this stage it is not really useful to know what is the free energy, just think in term of internal energy.
This is almost the same for such a small system which so few degrees of freedom.
It is conventional use to show the two states in terms of Ramachandran dihedral angles, which are denoted with Φ
and Ψ in Fig. belfast-2-transition-fig .
Generated by Doxygen
11.8 Belfast tutorial: Adaptive variables I
11.8.9
735
Examples
Now as a simple example, I want to show you that plotting some free dynamics trajectories shoot from the saddle
point, you get a different plot in the path collective variables if you use the right path or if you use the wrong path.
In Fig. belfast-2-good-bad-path-fig I show you two example of possible path that join the C7 eq and C7 ax metastable
states in alanine dipeptide. You might clearly expect that real (rare) trajectories that move from one basin to the
other would rather move along the black line than on the red line.
So, in this example we do a sort of "commmittor analysis" where we start shooting a number of free molecular
dynamics from the saddle point located at Φ = 0 and Ψ = −1 and we want to see which way do they go. Intuitively,
by assigning random velocities every time we should find part of the trajectories that move toward C7 eq and part
that move towards C7 ax.
I provided you with two directories, each containing a bash script script.sh whose core (it is a bit more complicated
in practice...) consists in:
#
# set how many runs you want to do
#
ntests=50
for i in ‘seq 1 $ntests‘
do
#
# assign a random velocity at each timestep by initializing the
#
sed s/SEED/$RANDOM/ md.mdp >newmd.mdp
#
# do the topology: this should write a topol.tpr
#
$GROMPP -c start.gro -p topol.top -f newmd.mdp
$GROMACS_BIN/$MDRUN -plumed plumed.dat
mv colvar colvar_$i
done
This runs 50 short MD runs (few hundreds steps) and just saves the colvar file into a labeled colvar file. In each
mdrun plumed is used to plot the collective variables and it is something that reads like the following:
# Phi
t1: TORSION ATOMS=5,7,9,15
# Psi
t2: TORSION ATOMS=7,9,15,17
# The right path
p1: PATHMSD REFERENCE=right_path.dat LAMBDA=15100.
# The wrong path
p2: PATHMSD REFERENCE=wrong_path.dat LAMBDA=8244.4
# Just a printout of all the stuff calculated so far
PRINT ARG=* STRIDE=2 FILE=colvar FMT=%12.8f
where I just want to plot Φ , Ψ and the two path collective variables. Note that each path has a different LAMBDA
parameters. Here the Ramachandran angles are plotted so you can realize which path is the system walking in
a more comfortable projection. This is of course fine in such a small system but whenever you have to deal with
larger systems and control hundreds of CVs at the same time, I think that path collective variables produce a more
intuitive description for what you want to do.
If you run the script simply with
pd@plumed:~> ./script.sh
then after a minute or so, you should have a directory which is full of colvar files. Let's revise together how the colvar
file is formatted:
Generated by Doxygen
736
#! FIELDS time t1 t2 p1.sss p1.zzz p2.sss p2.zzz
#! SET min_t1 -pi
#! SET max_t1 pi
#! SET min_t2 -pi
#! SET max_t2 pi
0.000000 -0.17752998 -1.01329788 13.87216908
0.004000 -0.13370142 -1.10611136 13.87613508
0.008000 -0.15633049 -1.14298481 13.88290617
0.012000 -0.23856451 -1.12343958 13.89969608
...
Tutorials
0.00005492
0.00004823
0.00004511
0.00004267
12.00532256
12.03390658
12.07203319
12.12872544
0.00233905
0.00255806
0.00273764
0.00284883
In first column you have the time, then t1 ( Φ) , then t2 ( Ψ ) and the path collective variables p1 and p2. Note
that the action PATHMSD calculates both the progress along the path (p1.sss) and the distance from it (p1.zzz) .
In PLUMED jargon, these are called "components". So a single Action (a line in plumed input) can calculate many
components at the same time. This is not always the case: sometimes by default you have one component but
specific flags may enable more components to be calculated (see DISTANCE for example). Note that the header
(all the part of a colvar file that contains # as first character) is telling already what it inside the file and eventually
also tells you if a variable is contained in boundaries (for example torsion angles, are periodic and their co-domain
is defined in -Pi and Pi ).
At the end of the script, you also have two additional scripts. One is named script_rama.gplt and the other is named
script_path.gplt. They contain some gnuplot commands that are very handy to visualize all the colvar files without
making you load one by one, that would be a pain.
Now, let's visualize the result from the wrong path directory. In order to do so, after having run the calculation, then
do
pd@plumed:~>gnuplot
gnuplot> load "script_rama.gplt"
what you see is that all the trajectories join the reactant and the product state along the low free energy path depicted
before.
Now if you try to load the same bunch of trajectories as a function of the progress along the path and the distance
from the path in the case of the wrong path then simply do
gnuplot> load "script_path_wrong.gplt"
What do you see? A number of trajectories move from the middle towards the right bottom side at low distance
from the path. In the middle of the progress along the path, you have higher distance. This is expected since the
distance zero corresponds to a unlikely, highly-energetic path which is unlikely to occur. Differently, if you now do
gnuplot> load "script_path_right.gplt"
You see that the path, compared to what happened before, run much closer to small distance from the path. This
means that the provided path is right and more representative of what happens in the reactive path.
Note that going at high distances can be also beneficial. It might help you to explore alternative paths that you have
not explored before. But beware, the more you get far from the path, the more states are accessible, in a similar way
as the fact that the surface of a sphere increase with its radius. The surface ramps up much faster than the radius
therefore you have a lots of states there. This means also high entropy, so many systems actually tend to drift to
high distances while, on the contrary, zero distance is never reached in practice (zero entropy system is impossible
to reach at finite temperature). So you can see by yourself that this can be a big can of worms. In particular, my
experience with path collective variables and biological systems tells me that most of time is hopeless to go to high
distances to find new path in many cases (for example, in folding). While this is worth whenever you think that the
paths are not too many (alternative routes in chemical reaction or enzymatic catalysis).
Generated by Doxygen
11.8 Belfast tutorial: Adaptive variables I
11.8.10
737
How to format my input?
Very often it is asked how to format a set of pdb to be suitably used with path collective variables. Here are some
tricks.
• When you dump the files with vmd or (for gromacs users, using trjcat), the pdb you obtain is re-indexed from
1. This is also the case when you select a sub-ensemble of atoms of the path (e.g. the heavy atoms only or
the backbone atoms). This is rather unfortunate and you have to fix is someway. My preference is to dump
the whole pdb but water (when I do not need it) and use some awk script to select the atoms I am interested
in.
• Pay attention to the last two column. These are occupancy and beta. With the first (occupancy) you set the
atoms which are used to perform the alignment. The atoms which have zero occupancy will not be used in the
alignment. The second column is beta and controls which atoms are used for the calculation of the distance
after having performed the alignment on the set of atoms which have nonzero occupancy column. In this way
you can align all your system by using a part of the system and calculate the distance respect to another set.
This is handy in case of protein-ligand. You set the alignment of the protein and you calculate the distance
based on the ligand and the part of the protein which is in contact with the protein. This is done for example
in this article.
• Plumed-GUI (version > 2.0) provides the Structure->Build reference structure... function to generate
inputs that conform to the above rules from within VMD.
• Note that all the atoms contained in the REFERENCE must be the same. You cannot have a variable number
of atoms in each pdb contained in the reference.
• The reference is composed as a set of concatenated PDB files that are interrupted by a TER/END/ENDMDL
card. Both HETATM and ATOM cards denote the atoms of the set.
• Include in the reference frames only the needed atoms. For example, if you have a methyl group involved in a
conformational transition, it might be that you do not want to include the hydrogen atoms of the methyl since
these rotate fast and probably they do not play ant relevant role.
11.8.11
Fast forward: metadynamics on the path
This section is actually set a bit forward but I included here for completeness now. It is recommended to be read
after you have an introduction on Metadynamics and to well-tempered Metadynamics in particular. Here I want to
show a couple of concept together.
• Path collective variables can be used for exploring alternative routes. It is effective in highly structure
molecules, while it is tricky on complex molecules whenever you have many competing routes
• Path collective variables suffer from problems at the endpoints (as the highly popular coordinates
COORDINATION for example) that can be cured with flexible hills and an appropriate reweighting procedure within the well-tempered Metadynamics scheme.
Let's go to the last problem. All comes from the derivative belfast-2-sder-eq. Whenever you have a point of phase
space which is similar to one of the endpoint than one of the points in the center then you get a s(X) which is 1
or N (where N is the number of frames composing the path collective variable). In this case that exponential will
dominate the others and you are left with a constant (since the derivative of RMSD is a constant since it is linear in
space). This means that, no matter what happens here, you have small force. Additionally you have small motion
in the CV space. You can move a lot in configuration space but if the closest point is one of the endpoint, your CV
value will always be one of the endpoint itself. So, if you use a fixed width of your CV which you retrieve from a
middle point in your path, this is not suitable at all at the endpoints where your CV fluctuates much less. On the
contrary if you pick the hills width by making a free dynamics on the end states you might pick some sigmas that are
smaller than what you might use in the middle of the path. This might give a rough free energy profile and definitely
Generated by Doxygen
738
Tutorials
more time to converge. A possible solution is to use the adaptive gaussian width scheme. In this scheme you adapt
the hills to their fluctuation in time. You find more details in [48] Additionally you also adopt a non spherical shape
taking into account variable correlation. So in this scheme you do not have to fix one sigma per variable sigma,
but just the time in which you calculate this correlation (another possibility is to calculate it from the compression of
phase space but will not be covered here). The input of metadynamics might become something like this
t1: TORSION ATOMS=5,7,9,15
t2: TORSION ATOMS=7,9,15,17
p1: PATHMSD REFERENCE=right_path.dat LAMBDA=15100.
p2: PATHMSD REFERENCE=wrong_path.dat LAMBDA=8244.4
#
# do a metadynamics on the right path, use adaptive hills whose decay time is 125 steps (250 fs)
# and rather standard WT parameters
#
meta: METAD ARG=p1.sss,p1.zzz ADAPTIVE=DIFF SIGMA=125 HEIGHT=2.4 TEMP=300 BIASFACTOR=12 PACE=125
PRINT ARG=* STRIDE=10 FILE=colvar FMT=%12.8f
You can find this example in the directory BIASED_DYNAMICS. After you run for a while it is interesting to have a
feeling for the change in shape of the hills. That you can do with
pd@plumed:~> gnuplot
gnuplot> p " plumed sum_hills --hills HILLS --negbias
--outfile negative_bias.dat --bin 100,100 --min -5,-0.0
and then calculate the correction. You can use the same hills file for that purpose. The initial transient time should
not matter if your simulation is long enough to see many recrossing and, secondly, you should check that the hills
height in the well tempered are small compared to the beginning.
pd@plumed:~> plumed sum_hills --histo HILLS --bin 100,100 --min -5,-0.005 --max 25,0.05 --kt 2.5 --sigma 0.5,0
Note that in the correction you should assign a sigma, that is a "trust radius" in which you think that whenever you
have a point somewhere, there in the neighborhood you assign a bin (it is done with Gaussian in reality, but this
does not matter much). This is the important point that compensates for the issues you might encounter putting
excessive large hills in places that you have not visited. It is nice to have a look to the correction and compare with
the hills in the same range.
Generated by Doxygen
11.9 Belfast tutorial: Adaptive variables II
gnuplot>
gnuplot>
gnuplot>
gnuplot>
gnuplot>
gnuplot>
gnuplot>
739
set pm3d
spl "correction.dat" u 1:2:3 w l
set contour
set cntrp lev incremental -20,4.,1000.
set view map
unset clabel
replot
You might notice that there are no contour in the unrealistic range, this means that the free energy correction is
impossible to calculate since it is too high (see Fig. belfast-2-metadpath-correction-fig ).
Now the last thing that one has to do to have the most plausible free energy landscape is to sum both the correction
and the negative bias produced. This can be easily done in gnuplot as follows:
gnuplot>
gnuplot>
gnuplot>
gnuplot>
gnuplot>
gnuplot>
gnuplot>
gnuplot>
gnuplot>
set pm3d
spl "Analysis>GISMO.
Generated by Doxygen
11.9 Belfast tutorial: Adaptive variables II
11.9.4.3
741
Finding collective variables
Right so lets come up with some CVs to analyze this trajectory with. As some of you may know we can understand
the conformation of proteins by looking at the Ramachandran angles. For those of you who don't know here is a
Wikipedia article:
http://en.wikipedia.org/wiki/Ramachandran_plot
Our protein has 32 Ramachandran angles. We'll come back to that. For the time being pick out a couple that you
think might be useful and construct a plumed input to calculate them and print them to a file. You will need to use
the TORSION and PRINT commands in order to do this. Once you have created your plumed input use driver to
calculate the torsional angles using the following command:
plumed driver --plumed plumed.dat --ixyz trajectory-short.xyz
If you have done this correctly you should have an output file containing your torsional angles. We can use vmd+←GISMO to visualize the relationship between the Ramachandran angles and the atomic configurations. To do this
first load the trajectory in VMD:
vmd trajectory-short.pdb
Then click on Extensions>Analysis>GISMO. A new window should open in this window click on File>Load colvars.
You will be asked to select a colvar file. Select the file that was output by the plumed calculation above. Once the
file is loaded you should be able to select the labels that you gave to the Ramachandran angles you calculated with
plumed. If you do so you will see that this data is plotted in the GISMO window so that you can interact with it and
the trajectory.
What can you conclude from this exercise. Do the CV values of the various frames appear in clusters in the plane?
Do points in different clusters correspond to structures that look the same or different? Are there similar looking
structures clustered together or are they always far apart? What can we conclude about the various basins in the
free energy landscape that have been explored in this trajectory? How many are there? Would your estimate be
the same if you tried the above estimate with a different pair of Ramachandran angles?
11.9.4.4
Dimensionality reduction
What we have done in most of the other exercises here is seek out a function that takes as input the position of all
the atoms in the system - a 3N dimensional vector, where N is the number of atoms. This function then outputs
a single number - the value of the collective variable - that tells us where in a low dimensional space we should
project that configuration. Problems can arise because this collective-variable function is many-to-one. As you
have hopefully seen in the previous exercise markedly different configurations of the protein can actually have quite
similar values of a particular Ramachandran angle.
We are going to spend the rest of this session introducing an alternative approach to this business of finding
collective variables. In this alternative approach we are going to stop trying to seek out a function that can take
any configuration of the atoms (any 3N -dimensional vector) and find its low dimensional projection on the collective
variable axis. Instead we are going to take a set of configurations of the atoms (a set of 3N -dimensional vectors
of atom positions) and try to find a sensible set of projections for these configurations. We already touched on
this idea earlier when we looked at paths. Our assumption, when we introduced this idea, was that we could find
an ordered set of high-dimensional configurations that represented the transition pathway the system takes as it
crossed a barrier and changed between two particularly interesting configurations. Lets say we have a path defined
by four reference configurations - this implies that to travel between the configurations at the start and the end of
this path you have to pass through configuration 1, then configuration 2, then configuration 3 and then configuration
4. This ordering means that the numbers 1 through 4 constitute sensible projections of these high-dimensional
configurations. The numbers 1 through 4 all lie on a single Cartesian axis - a low-dimensional space.
Generated by Doxygen
742
Tutorials
The problem when it comes to applying this idea to the data that we have in the trajectory-short trajectory is that
we have no information on the "order" of these points. We have not been told that this trajectory represents the
transition between two interesting points in phase space and thus we cannot apply the logic of paths. Hence, to
seek out a low dimensional representation we are going to try and find a representation of this data we are going to
seek out an isometry between the space containing the 3N -dimensional vectors of atom positions and some
lower-dimensional space. This idea is explained in more detail in the following video .
Let's now generate our isometric embedding. You will need to create a plumed input file that contains the following
instructions:
CLASSICAL_MDS ...
ATOMS=1-256
METRIC=OPTIMAL-FAST
NLOW_DIM=2
OUTPUT_FILE=rmsd-embed
... CLASSICAL_MDS
You should then run this calculation using the following command:
plumed driver --ixyz trajectory-short.xyz --plumed plumed.dat
This should generate an output file called rmsd-embed. You should now be able to use VMD+GISMO to visualize
this output.
Do the CV values of the various frames appear in clusters in the plane? Do points in different clusters correspond to
structures that look the same or different? Are there similar looking structures clustered together or are they always
far apart? What can we conclude about the various basins in the free energy landscape that have been explored in
this trajectory? How many are there? Do you think this gives you a fuller picture of the trajectory than the ones you
obtained by considering Ramachandran angles?
11.9.5
Extensions
As discussed in the previous section this approach to trajectory analysis works by calculating distances between
pairs of atomic configurations. Projections corresponding to these configurations are then generated in the low
dimensional space in a way that tries to preserve these pairwise distances. There are, however, an infinite number
of ways of calculating the distance between two high-dimensional configurations. In the previous section we used
the RMSD distance but you could equally use the DRMSD distance. You could even try calculating a large number
of collective variables for each of the high-dimensional points and seeing how much these all changed. You can use
these different types of distances with the CLASSICAL_MDS action that was introduced in the previous section.
If you have time less at the end of the session read the manual for the CLASSICAL_MDS action and see if you
can calculate an MDS projection using an alternative definition of the distances between configurations. Some
suggestions to try in order of increasing difficulty: DRMSD, how much the full set of 32 Ramachandran angles
change and the change in the contact map
11.9.6
Further Reading
There is a growing community of people using these ideas to analyze trajectory data. Some start points for investigating their work in more detail are:
• http://epfl-cosmo.github.io/sketchmap/index.html?page=main
• http://www.annualreviews.org/doi/abs/10.1146/annurev-physchem-040412-110006
Generated by Doxygen
11.10 Belfast tutorial: Umbrella sampling
743
11.10
Belfast tutorial: Umbrella sampling
11.10.1
Aims
In the previous lectures we learned how to compute collective variables (CVs) from atomic positions. We will now
learn how one can add a bias potential to enforce the exploration of a particular region of the space. We will also
see how it is possible to bias CVs so as to enhance the sampling of events hindered by large free-energy barriers
and how to analyze this kind of simulation. This technique is known as "umbrella sampling" and can be used in
combination with the weighted-histogram analysis method to compute free-energy landscapes. In this tutorial we
will use simple collective variables, but the very same approach can be used with any kind of collective variable.
11.10.2
Summary of theory
11.10.2.1
Biased sampling
A system at temperature T samples conformations from the canonical ensemble:
P (q) ∝ e
U (q)
BT
−k
. Here q are the microscopic coordinates and kB is the Boltzmann constant. Since q is a highly dimensional
vector, it is often convenient to analyze it in terms of a few collective variables (see Belfast tutorial: Analyzing CVs
, Belfast tutorial: Adaptive variables I , and Belfast tutorial: Adaptive variables II ). The probability distribution for a
CV s is
Z
P (s) ∝
U (q)
BT
−k
dqe
δ(s − s(q))
This probability can be expressed in energy units as a free energy landscape F (s):
F (s) = −kB T log P (s)
.
Now we would like to modify the potential by adding a term that depends on the CV only. That is, instead of using
U (q), we use U (q) + V (s(q)). There are several reasons why one would like to introduce this potential. One is
to avoid that the system samples some un-desired portion of the conformational space. As an example, imagine
that you want to study dissociation of a complex of two molecules. If you perform a very long simulation you will
be able to see association and dissociation. However, the typical time required for association will depend on the
size of the simulation box. It could be thus convenient to limit the exploration to conformations where the distance
between the two molecules is lower than a given threshold. This could be done by adding a bias potential on the
distance between the two molecules. Another example is the simulation of a portion of a large molecule taken out
from its initial context. The fragment alone could be unstable, and one might want to add additional potentials to
keep the fragment in place. This could be done by adding a bias potential on some measure of the distance from
the experimental structure (e.g. on root-mean-square deviation).
Whatever CV we decide to bias, it is very important to recognize which is the effect of this bias and, if necessary,
remove it a posteriori. The biased distribution of the CV will be
0
Z
P (s) ∝
−
dqe
U (q)+V (s(q))
kB T
δ(s − s(q)) ∝ e
−
V (s(q))
kB T
P (s)
and the biased free energy landscape
F 0 (s) = −kB T log P 0 (s) = F (s) + V (s) + C
Thus, the effect of a bias potential on the free energy is additive. Also notice the presence of an undetermined
constant C . This constant is irrelevant for what concerns free-energy differences and barriers, but will be important
Generated by Doxygen
744
Tutorials
later when we will learn the weighted-histogram method. Obviously the last equation can be inverted so as to obtain
the original, unbiased free-energy landscape from the biased one just subtracting the bias potential
F (s) = F 0 (s) − V (s) + C
Additionally, one might be interested in recovering the distribution of an arbitrary observable. E.g., one could
add a bias on the distance between two molecules and be willing to compute the unbiased distribution of some
torsional angle. In this case there is no straightforward relationship that can be used, and one has to go back to the
relationship between the microscopic probabilities:
P (q) ∝ P 0 (q)e
V (s(q))
kB T
The consequence of this expression is that one can obtained any kind of unbiased information from a biased
simulation just by weighting every sampled conformation with a weight
w∝e
V (s(q))
kB T
That is, frames that have been explored in spite of a high (disfavoring) bias potential V will be counted more than
frames that has been explored with a less disfavoring bias potential.
11.10.2.2
Umbrella sampling
Often in interesting cases the free-energy landscape has several local minima. If these minima have free-energy
differences that are on the order of a few times kB T they might all be relevant. However, if they are separated by
a high saddle point in the free-energy landscape (i.e. a low probability region) than the transition between one and
the other will take a lot of time and these minima will correspond to metastable states. The transition between one
minimum and the other could require a time scale which is out of reach for molecular dynamics. In these situations,
one could take inspiration from catalysis and try to favor in a controlled manner the conformations corresponding to
the transition state.
Imagine that you know since the beginning the shape of the free-energy landscape F (s) as a function of one CV s.
If you perform a molecular dynamics simulation using a bias potential which is exactly equal to −F (s), the biased
free-energy landscape will be flat and barrier less. This potential acts as an "umbrella" that helps you to safely cross
the transition state in spite of its high free energy.
It is however difficult to have an a priori guess of the free-energy landscape. We will see later how adaptive
techniques such as metadynamics (Belfast tutorial: Metadynamics) can be used to this aim. Because of this reason,
umbrella sampling is often used in a slightly different manner.
Imagine that you do not know the exact height of the free-energy barrier but you have an idea of where the barrier
is located. You could try to just favor the sampling of the transition state by adding a harmonic restraint on the CV,
e.g. in the form
V (s) =
k
(s − s0 )2
2
. The sampled distribution will be
P 0 (q) ∝ P (q)e
−k(s(q)−s0 )2
2kB T
For large values of k , only points close to s0 will be explored. It is thus clear how one can force the system to explore
only a predefined region of the space adding such a restraint. By combining simulations performed with different
values of s0 , one could obtain a continuous set of simulations going from one minimum to the other crossing the
transition state. In the next section we will see how to combine the information from these simulations.
Generated by Doxygen
11.10 Belfast tutorial: Umbrella sampling
11.10.2.3
745
Weighted histogram analysis method
Let's now consider multiple simulations performed with restraints located in different positions. In particular, we will
consider the i-th bias potential as Vi . The probability to observe a given value of the collective variable s is:
Pi (s) = R
P (s)e
V (s)
BT
− ki
ds0 P (s0 )e
−
V (s)
BT
− ki
P (s)e
=
Zi
Vi (s0 )
kB T
where
X
Zi =
e−(U (q)+Vi (q))
q
The likelihood for the observation of a sequence of snapshots qi (t) (where i is the index of the trajectory and t
is time) is just the product of the probability of each of the snapshots. We use here the minus-logarithm of the
likelihood (so that the product is converted to a sum) that can be written as
L=−
XZ
dt log Pi (si (t)) =
Vi (si (t))
dt − log P (si (t)) +
+ log Zi
kB T
XZ
i
i
δL
δP (s)
= 0. After some boring algebra the following expression can
V (s)
− ki T
XZ
B
δsi (t),s
e
dt −
0=
+
P
(s)
Z
i
i
One can then maximize the likelihood by setting
be obtained
In this equation we aim at finding P (s). However, also the list of normalization factors Zi is unknown, and they
should be found self consistently. Thus one can find the solution as
N (s)
P (s) ∝
P R
i
dt e
−
Vi (s)
kB T
Zi
where Z is self consistently determined as
Z
Zi ∝
ds0 P (s0 )e
−
Vi (s0 )
kB T
These are the WHAM equations that are traditionally solved to derive the unbiased probability P (s) by the combination of multiple restrained simulations. To make a slightly more general implementation, one can compute the
weights that should be assigned to each snapshot, that turn out to be:
wi (t) ∝ P R
j
1
−βVj (si (t))
dt e Zj
The normalization factors can in turn be found from the weights as
P R
Zi ∝
j
dte−βVi (sj (t)) wj (t)
P R
dtwj (t)
j
This allows to straightforwardly compute averages related to other, non-biased degrees of freedom, and it is thus
a bit more flexible. It is sufficient to pre-compute this factors w and use them to weight every single frame in the
trajectory.
11.10.3
Learning Outcomes
Once this tutorial is completed students will know how to:
• Setup simulations with restraints.
• Use multiple-restraint umbrella sampling simulations to enhance the transition across a free-energy barrier.
• Analyze the results and compute weighted averages and free-energy profiles.
Generated by Doxygen
746
Tutorials
11.10.4
Resources
The tarball for this project contains the following files:
• A gromacs topology (topol.top), configuration (conf.gro), and control file (grompp.mdp). They should not be
needed.
• A gromacs binary file (topol.tpr). This is enough for running this system.
• A small C++ program that computes WHAM (wham.cpp) and a script that can be used to feed it (wham.sh)
By working in the directory where the topol.tpr file is stored, one can launch gromacs with the command
gmx_mpi mdrun -plumed plumed.dat -nsteps 100000
(notice that the -nsteps flag allows the number of steps to be changed).
11.10.5
Instructions
11.10.5.1
The model system
We here use a a model system alanine dipeptide with CHARM27 all atom force field already seen in the previous
section.
11.10.5.2
Restrained simulations
The simplest way in which one might influence a CV is by forcing the system to stay close to a chosen value during
the simulation. This is achieved with a restraining potential that PLUMED provides via the directive RESTRAINT.
In the umbrella sampling method a bias potential is added so as to favor the exploration of some regions of the
conformational space and to disfavor the exploration of other regions [92] . A properly chosen bias potential could
allow for example to favor the transition state sampling thus enhancing the transition state for a conformational
transition. However, choosing such a potential is not trivial. In a later section we will see how metadynamics can be
used to this aim. The simplest way to use umbrella sampling is that to apply harmonic constraints to one or more
CVs.
We will now see how to enforce the exploration of a the neighborhood of a selected point the CV space using a
RESTRAINT potential.
# set up two variables for Phi and Psi dihedral angles
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
#
# Impose an umbrella potential on CV 1 and CV 2
# with a spring constant of 500 kjoule/mol
# at fixed points on the Ramachandran plot
#
restraint-phi: RESTRAINT ARG=phi KAPPA=500 AT=-0.3
restraint-psi: RESTRAINT ARG=psi KAPPA=500 AT=+0.3
# monitor the two variables and the bias potential from the two restraints
PRINT STRIDE=10 ARG=phi,psi,restraint-phi.bias,restraint-psi.bias FILE=COLVAR
Generated by Doxygen
11.10 Belfast tutorial: Umbrella sampling
747
(see TORSION, RESTRAINT, and PRINT).
The syntax for the command RESTRAINT is rather trivial. The directive is followed by a keyword ARG followed by
the label of the CV on which the umbrella potential has to act. The keyword KAPPA determines the hardness of
the spring constant and its units are [Energy units]/[Units of the CV ]. The additional potential introduced by the
UMBRELLA takes the form of a simple Hooke’s law:
U (s) =
k
(x − x0 )2
2
.
where x0 is the value specified following the AT keyword. The choice of AT ( x0 ) is obviously depending on the
specific case. KAPPA ( k ) is typically chosen not to affect too much the intrinsic fluctuations of the system. A typical
recipe is k ≈ kσB2T , where σ 2 is the variance of the CV in a free simulation). In real applications, one must be careful
with values of k larger than kσB2T because they could break down the molecular dynamics integrator.
The CVs as well as the two bias potentials are shown in the COLVAR file. For this specific input the COLVAR file
has in first column the time, in the second the value of φ, in the third the value of ψ , in the fourth the the additional
potential introduced by the restraint on φ and in the fifth the additional potential introduced by the restraint on ψ .
It may happen that one wants that a given CV just stays within a given range of values. This is achieved in plumed
through the directives UPPER_WALLS and LOWER_WALLS that act on specific collective variables and limit the
exploration within given ranges.
11.10.5.3
Reweighting the results
Now consider a simulation performed restraining the variable φ:
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
restraint-phi: RESTRAINT ARG=phi KAPPA=10.0 AT=-2
PRINT STRIDE=10 ARG=phi,psi,restraint-phi.bias FILE=COLVAR10
and compare the result with the one from a single simulation with no restraint
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
# we use a "dummy" restraint with strength zero here
restraint-phi: RESTRAINT ARG=phi KAPPA=0.0 AT=-2
PRINT STRIDE=10 ARG=phi,psi,restraint-phi.bias FILE=COLVAR0
Plot the time dependence of φ in the two cases and try to understand the difference.
Now let's try to compute the probability that ψ falls within a given range, say between 1 and 2. This can be done
e.g. with this shell script
> grep -v \# COLVAR0 | tail -n 80000 |
awk ’{if($3>1 && $3<2)a++; else b++;}END{print a/(a+b)}’
Notice that we here considered only the last 80000 frames in the average. Look at the time series for ψ and guess
why. Also notice that the script is removing the initial comments. After this trivial pre-processing, the script is just
counting how many times the third column ( ψ ) lies between 1 and 2 and how many times it doesn't. At the end it
prints the number of times the variable is between 1 and 2 divided by the total count. The result should be something
around 0.40. Now try to do it on trajectories generated with different values of AT. Does the result depend on AT?
We can now try to reweight the result so as to get rid of the bias introduced by the restraint. Since the reweighting
V
factor is just exp( kB
T the script should be modified as
> grep -v \# COLVAR10 | tail -n 80000 |
awk ’{w=exp($4/2.5); if($3>1 && $3<2)a+=w; else b+=w;}END{print a/(a+b)}’
Notice that 2.5 is just kB T in kj/mol units.
Repeat this calculation for different values of AT. Does the result depend on AT?
Generated by Doxygen
748
11.10.5.4
Tutorials
A free-energy landscape
One can also count the probability of an angle to be in a precise bin. The logarithm of this quantity, in kB T units, is
the free-energy associated to that bin. There are several ways to compute histograms, either with PLUMED or with
external programs. Here I decided to use awk.
grep -v \# COLVAR10 | tail -n 80000 |
awk ’BEGIN{
min1=-3.14159265358979
max1=+3.14159265358979
min2=-3.14159265358979
max2=+3.14159265358979
nb1=100;
nb2=100;
for(i1=0;i1 plotme
You can then plot the "plotme" file with
gnuplot> set pm3d map
gnuplot> splot "plotme"
11.10.5.5
Combining multiple restraints
In the last paragraph you have seen how to reweight simulations done with restraints in different positions to obtain
virtually the same result. Let's now see how to combine data from multiple restraint simulations. A possible choice
is to download and use the WHAM software here, which is well documented. This is probably the best idea for
analyzing a real simulation.
For the sake of learning a bit, we will use a different approach here, namely we will use a short C++ program that
implements the weight calculation. Notice that whereas people typically use harmonic restraints in this framework,
PLUMED offers a very large variety of bias potentials. For this reason we will keep things as general as possible
and use an approach that can be in principle used also to combine simulation with restraint on different variables or
with complicated bias potential.
The first step is to generate several simulations with different positions of the restraint, gradually going from say -2
to +2. You can obtain them using e.g. the following script:
for AT in -2.0 -1.5 -1.0 -0.5 +0.0 +0.5 +1.0 +1.5 +2.0
do
cat >plumed.dat << EOF
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
#
# Impose an umbrella potential on CV 1 and CV 2
# with a spring constant of 500 kjoule/mol
# at fixed points on the Ramachandran plot
#
restraint-phi: RESTRAINT ARG=phi KAPPA=40.0 AT=$AT
# monitor the two variables and the bias potential from the two restraints
PRINT STRIDE=10 ARG=phi,psi,restraint-phi.bias FILE=COLVAR$AT
EOF
gmx_mpi mdrun -plumed plumed.dat -nsteps 100000 -x traj$AT.xtc
done
Generated by Doxygen
11.10 Belfast tutorial: Umbrella sampling
749
Notice that we are here saving separate trajectories for the separate simulation, as well as separate colvar files. In
each simulation the restraint is located in a different position. Have a look at the plot of (phi,psi) for the different
simulations to understand what is happening.
An often misunderstood fact about WHAM is that data of the different trajectories can be mixed and it is not necessary to keep track of which restraint was used to produce every single frame. Let's get the concatenated trajectory
gmx_mpi trjcat -cat -f traj*.xtc -o alltraj.xtc
Now we should compute the value of each of the bias potentials on the entire (concatenated) trajectory
for AT in -2.0 -1.5 -1.0 -0.5 +0.0 +0.5 +1.0 +1.5 +2.0
do
cat >plumed.dat << EOF
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
restraint-phi: RESTRAINT ARG=phi KAPPA=40.0 AT=$AT
# monitor the two variables and the bias potential from the two restraints
PRINT STRIDE=10 ARG=phi,psi,restraint-phi.bias FILE=ALLCOLVAR$AT
EOF
plumed driver --mf_xtc alltraj.xtc --trajectory-stride=10 --plumed plumed.dat
done
It is very important that this script is consistent with the one used to generate the multiple simulations above. Now,
single files named ALLCOLVARXX will contain on the fourth column the value of the bias centered in XX computed
on the entire concatenated trajectory.
Next step is to compile the C++ program that computes weights self-consistently solving the WHAM equations. This
is named wham.cpp and can be compiled with
g++ -O3 wham.cpp -o wham.x
and can be then used through a wrapper script wham.sh as
./wham.sh ALLCOLVAR* > colvar
The resulting colvar file will contain 3 columns: time, phi, and psi, plus the weights obtained from WHAM written in
logarithmic scale. That is, the file will contain kB T log w.
Try now to use this file to compute the unbiased free-energy landscape as a function of phi and psi. You can use
the script that you used earlier to compute histogram.
11.10.6
Comments
11.10.6.1
How does PLUMED work
The fact that when you add a force on the collective variable PLUMED can force the atoms to do something depends
on the fact that the collective variables implemented in PLUMED has analytical derivatives. By biasing the value of
a single CV one turns to affect the time evolution of the system itself. Notice that some of the collective variables
could be implemented without derivatives (either because the developers were lazy or because the CVs cannot be
derived). In this case you might want to have a look at the NUMERICAL_DERIVATIVES option.
Generated by Doxygen
750
Tutorials
11.10.7
Further Reading
Umbrella sampling method is a widely used technique. You can find several resources on the web, e.g.:
• http://en.wikipedia.org/wiki/Umbrella_sampling
11.11
Belfast tutorial: Out of equilibrium dynamics
In plumed you can bring a system in a specific state in a collective variable by means of the MOVINGRESTRAINT
directive. This directive is very flexible and allows for a programmed series moving restraints. This technique can
be used also to sample multiple events within a single simulation. Here I will explain the concepts of it and show
some examples
11.11.1
Resources
Here is the tarball with the files referenced in the following .
11.11.2
Steered MD
Steered MD (SMD) is often used to drag the system from an initial configuration to a final one by pulling one or
more CVs. Most of time the aim of such simulations is to prepare the system in a particular state or produce nice
snapshots for a cool movie. All the CVs present in PLUMED can be used in SMD.
In SMD the Hamiltonian of the system H is modified into
Hλ . This new Hamiltonian contains now another new term which now depends on time only via a Harmonic potential
centered on a point which moves linear with time
Hλ (X, t)
=
=
=
H(X) + Uλ (X, t)
k(t)
(s(X) − λ(t))2
H(X) +
2
k(t)
(s(X) − s0 − vt)2 .
H(X) +
2
This means that if the k is tight enough the system will follow closely the center of the moving harmonic spring.
But be careful, if the spring constant is too hard your equations of motion will now keep up since they are tuned to
the fastest motion in your system so if you artificially introduce a higher frequency in your system you'll screw up
the dynamics. The same is true for the pulling speed v . As a matter of fact I never encountered the case where
I had to lower the time step and I could all the time be happy just by making a softer spring constant or a slower
steering speed. Generally, integrators of equations of motion like velocity-Verlet are very tolerant. Note that one can
also make the spring constant depend on time and this, as we will see later in the examples is particularly useful to
prepare your state.
In simulations, it is more convenient to adopt a situation where you specify only the starting point, the final point of
collective variables and the time in which you want to cover the transition. That's why the plumed input is done in
such a way.
For example, let's go back to the alanine dipeptide example encountered in The molecule of the day: alanine dipeptide.
Let's say that now we want to steer from C7 eq to C7 ax. If you think, just by dragging along the Φ dihedral angle
from a value of -1 to a value 1 should be enough to the state of interest. Additionally, it might be important to you
not to stress the system too much, so you might want first to increase the k first so to lock the system in Φ = −1,
then move it gently to Φ = 1 and then release again your spring constant so to end up to an equilibrated and
unconstrained state. This you can program in PLUMED like this
Generated by Doxygen
11.11 Belfast tutorial: Out of equilibrium dynamics
751
# set up two variables for Phi and Psi dihedral angles
# drag this
phi: TORSION ATOMS=5,7,9,15
# this is just to monitor that you end up in the interesting state
psi: TORSION ATOMS=7,9,15,17
# the movingrestraint
restraint: ...
MOVINGRESTRAINT
ARG=phi
AT0=-1.0 STEP0=0
KAPPA0=0
AT1=-1.0 STEP1=2000
KAPPA1=1000
AT2=1.0 STEP2=4000
KAPPA2=1000
AT3=1.0 STEP3=6000
KAPPA3=0
...
# monitor the two variables and various restraint outputs
PRINT STRIDE=10 ARG=* FILE=COLVAR
Please note the syntax of MOVINGRESTRAINT : You need one (or more) argument(s) and a set of steps denote
by AT x, STEP x, KAPPA x where x is a incremental starting from 0 that assign the center and the harness of the
spring at step STEP x. What happens in between is a linear interpolation of the AT and KAPPA parameters. If those
are identical in two consecutive steps then nothing is happening to that parameter. So if you put the same KAPPA
and AT value in two different STEP keywords then this will give you an umbrella potential placed in the same point
between the two time intervals defined by STEP. Note that you need to run a bit more than 6000 steps because
after this your system has no more restraints so the actual thermalization period starts here.
The COLVAR file produced has the following shape
#! FIELDS time phi psi restraint.bias
#! SET min_phi -pi
#! SET max_phi pi
#! SET min_psi -pi
#! SET max_psi pi
0.000000 -1.409958 1.246193 0.000000
0.020000 -1.432352 1.256545 0.467321
0.040000 -1.438652 1.278405 0.962080
0.060000 -1.388132 1.283709 1.129846
0.080000 -1.360254 1.275045 1.297832
...
restraint.force2 restraint.phi_cntr restraint.phi_work
0.000000 -1.000000 0.000000
4.673211 -1.000000 0.441499
19.241592 -1.000000 0.918101
33.895372 -1.000000 1.344595
51.913277 -1.000000 1.691475
So we have time, phi, psi and the bias from the moving restraint. Note that at step 0 is zero since we imposed this
to start from zero and ramp up in the first 2000 steps up to a value of 2000 kJ/mol/rad∧ 2. It increases immediately
since already at step 1 the harmonic potential is going to be increased in bits towards the value of 1000 which is set
by KAPPA. The value of restraint.force2 is the squared force (which is a proxy of the force magnitude, despite the
direction) on the CV.
−
∂Hλ (X, t)
∂s
= −(s(X) − s0 − vt)
Note that the actual force on an atom of the system involved in a CV is instead
−
∂Hλ (X, t)
∂xi
= −
∂Hλ (X, t) ∂s
∂s
∂xi
= −(s(X) − s0 − vt)
∂s
∂xi
This is important because in CVs that have a derivative that change significantly with space then you might have
regions in which no force is exerted while in others you might have an enormous force on it. Typically this is the case
of sigmoid functions that are used in coordination numbers in which, in the tails, they are basically flat as a function
Generated by Doxygen
752
Tutorials
of particle positions. Additionally note that this happens on any force-based enhanced-sampling algorithm so keep
it in mind. Very often people miss this aspect and complain either that a CV or a enhanced-sampling method does
not work. This is another good reason to use tight spring force so to compensate in the force the lack of derivative
from the CV.
The other argument in colvar is restraint.phi_cntr which is the center of the harmonic potential. This is a useful
quantity so you may know how close the system is following the center of harmonic potential (more on this below).
The last parameter is restraint.phi_work. The work is defined as
Z
ts
dt
W =
0
∂Hλ (t)
∂t
so this is changing only when the Hamiltonian is changing with time. There are two time dependent contributions
in this integral: one can come from the fact that k(t) changes with time and another from the fact that the center of
the spring potential is changing with time.
Z
W
=
=
=
=
'
ts
∂Hλ (t)
∂t
0
Z ts
Z ts
∂Hλ (t) ∂λ(t)
∂Hλ (t) ∂k
dt
+
dt
∂λ
∂t
∂k ∂t
0
0
Z ts
Z ts
∂λ(t)
(s(X) − λ(t))2 ∂k
dt +
dt
−k(t)(s(X) − λ(t))
∂t
2
∂t
0
0
Z ts
Z ts
(s(X) − λ(t))2 ∂k
dt
−k(t)(s(X) − λ(t))vdt +
2
∂t
0
0
X
X (s(X(ti )) − λ(ti ))2
−k(ti )(s(X(ti )) − λ(ti ))∆λ(ti ) +
∆k(ti )
2
i
i
dt
where we denoted ∆λ(ti ) the difference of the center of the harmonic potential respect to the step before and
∆k(ti ) is the difference in spring constant respect to the step before. So in the exercised proposed in the first
phase you see only the second part of the work since this is the part connected with the spring constant increase.
After this phase you see the increase due to the motion of the center and then you later the release of the spring
constant.
The work profile as function of time when steering ala dipeptide along the Φ variable.
This you get with gnuplot:
pd@plumed:~>gnuplot
gnuplot> p "COLVAR" u 1:7 w lp
Another couple of interesting thing that you can check is
• Is my system finally in the C7ax ? Plot the two dihedral to have a sense if we are in the right state. You know
the target position what should look like, right?
- Is my system moving close to the center of the harmonic potential? This is important and we will see why in
a while.
Generated by Doxygen
11.11 Belfast tutorial: Out of equilibrium dynamics
11.11.3
753
Moving on a more complex path
Very often it is useful to use this moving restraint to make a fancier schedule by using nice properties of
MOVINGRESTRAINT. For example you can plan a schedule to drive multiple CVs at the same time in specific
point of the phase space and also to stop for a while in specific using a fixed harmonic potential. This can be handy
in case of an umbrella sampling run where you might want to explore a 1-dimensional landscape by acquiring some
statistics in one point and then moving to the next to acquire more statistics. With MOVINGRESTRAINT you can
do it in only one file. To give an example of such capabilities, let's say that we want to move from C7eq vertically
toward Φ = −1.5; Ψ = −1.3, stop by for a while (e.g. to acquire a statistics that you might need for an umbrella
sampling), then moving toward Φ = 1.3; Ψ = −1.3 which roughly corresponds to C7ax.
This can be programmed conveniently with MOVINGRESTRAINT by adopting the following schedule
# set up two variables for Phi and Psi dihedral angles
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
# the movingrestraint
restraint: ...
MOVINGRESTRAINT
ARG=phi,psi
AT0=-1.5,1.3 STEP0=0
KAPPA0=0,0
AT1=-1.5,1.3 STEP1=2000
KAPPA1=1000,1000
AT2=-1.5,-1.3 STEP2=4000
KAPPA2=1000,1000
AT3=-1.5,-1.3 STEP3=4000
KAPPA3=1000,1000
AT4=1.3,-1.3 STEP4=6000
KAPPA4=1000,1000
AT5=1.3,-1.3 STEP5=8000
KAPPA5=0,0
...
# monitor the two variables and various restraint outputs
PRINT STRIDE=10 ARG=* FILE=COLVAR
Note that by adding two arguments for moving restraint, now I am allowed to put two values (separated by comma,
as usual for multiple values in PLUMED) and correspondingly two KAPPA values. One for each variable. Please
note that no space must be used between the arguments! This is a very common fault in writing the inputs.
By plotting the instantaneous value of the variables and the value of the center of the harmonic potentials we can
inspect the pathways that we make the system walk on the Ramachandran plot. (How to do this? Have a look to
the header of COLVAR file to plot the right fields)
.png
Plot of the double steering schedule using MOVINGRESTRAINT
11.11.4
Why work is important?
The work as we have seen is the cumulative change of the Hamiltonian in time. So it is connected with the change
in energy of your system while you move it around. It has also a more important connection with the free energy via
the Jarzynski equation which reads
∆F = −β −1 lnhexp−βW i
This is important and says that potentially you can calculate the free energy even by driving your system very fast
and out of equilibrium between two states of your interest. Unfortunately this in practice not possible since the
accurate calculation of the quantity hexp−βW i has a huge associated error bar since it involves the average of a
noisy quantity (the work) that appears in the exponential. So, before going wild with SMD, I want to make a small
exercise on how tricky that is even for the smallest system.
Now we run, say 30 SMD run and we calculate the free energy difference by using Jarzynski equality and see how
this differs from the average. First note that the average hexp−βW i is an average over a number of steered MD
runs which start from the same value of CV and reach the final value of CV. So it is important to create initially an
Generated by Doxygen
754
Tutorials
ensemble of states which are compatible with a given value of CVs. Let's assume that we can do this by using a
restrained MD in a point (say at P hi = −1.5). In practice the umbrella biases a bit your distribution and the best
situation would be to do this with a flat bottom potential and then choosing the snapshot that correspond to the
wanted starting value and start from them.
In the directory JARZ/MAKE_ENSEMBLE you find the script to run. After you generate the constrained ensemble
this needs to be translated from xtc format to something that GROMACS is able to read in input, typically a more
convenient gro file. To do so just to
pd@plumed:~> echo 0 | trjconv_mpi-dp-pl -f traj.xtc -s topol.tpr -o all.gro
pd@plumed:~> awk ’BEGIN{i=1}{if($1=="Generated"){outfile=sprintf("start_%d.gro",i);i++}print >>outfile; if(NF=
This will generate a set of numbered gro files. Now copy them in the parallel directory MAKE_STEER. There you
will find a script (script.sh) where you can set the number of runs that you want to go for. Just try 20 and let it
run. Will take short time. The script will also produce a script_rama.gplt that you can use to visualize all the work
performed in a single gnuplot session. Just do:
pd@plumed:~>gnuplot
gnuplot> load "script_work.gplt"
What you see is something like in Fig.
There are a number of interesting fact here. First you see that different starting points may end with very different
work values. Not bad, one would say, since Jarzyinsi equality is saying that we can make an average and everything
will be OK. So now calculate the average work by using the following bash one-liner:
pd@plumed:~> ntest=20; for i in ‘seq 1 $ntest‘ ; do tail -1 colvar_$i | awk ’{print $7 }’ ; done | awk ’{g+=ex
For my test, what I get is a value of
FREE ENERGY ESTIMATE
17.482
STDEV
7.40342
and what this is saying is that the only thing that matters is the lowest work that I sampled. This has such an
enormous weight over all the other trajectories that will do so that it will be the only other to count, and all the other
do not matter much. So it is a kind of a waste of time. Also the standard deviation is rather high and probably it might
well be that you obtain a much better result by using a standard umbrella sampling where you can use profitably
most of the statistics. Here you waste most of the statistics indeed, since only the lowest work sampled will matter.
Some important point for doing some further exercises:
• How does the work distribution change if you increase the simulation time? Note that you have to increase
both the time in the md.mdp file and in the plumed.dat file.
• How the work change if you now use a softer spring constant? And a harder one?
• In particular, what happens when you have softer spring constant, say 10? This does not look like working?
Can you guess what is going on there from an analysis of COLVAR files only?
• Have a look of the trajectories in the Ramachandran plot in case of fast simulations and slow simulation. What
can you observe? Is there a correlation between steering speed and how often you can go on the low energy
path?
Generated by Doxygen
11.12 Belfast tutorial: Metadynamics
11.11.5
755
Targeted MD
Targeted MD can be seen as a special case of steered MD where the RMSD from a reference structure is used
as a collective variable. It can be used for example if one wants to prepare the system so that the coordinates of
selected atoms are as close as possible to a target pdb structure.
As an example we can take alanine dipeptide again
# set up two variables for Phi and Psi dihedral angles
# these variables will be just monitored to see what happens
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
# creates a CV that measures the RMSD from a reference pdb structure
# the RMSD is measured after OPTIMAL alignment with the target structure
rmsd: RMSD REFERENCE=c7ax.pdb TYPE=OPTIMAL
# the movingrestraint
restraint: ...
MOVINGRESTRAINT
ARG=rmsd
AT0=0.0 STEP0=0
KAPPA0=0
AT1=0.0 STEP1=5000
KAPPA1=10000
...
# monitor the two variables and various restraint outputs
PRINT STRIDE=10 ARG=* FILE=COLVAR
(see TORSION, RMSD, MOVINGRESTRAINT, and PRINT).
Note that RMSD should be provided a reference structure in pdb format and can contain part of the system but
the second column (the index) must reflect that of the full pdb so that PLUMED knows specifically which atom
to drag where. The MOVINGRESTRAINT bias potential here acts on the rmsd, and the other two variables (phi
and psi) are untouched. Notice that whereas the force from the restraint should be applied at every step (thus
rmsd is computed at every step) the two torsion angles are computed only every 10 steps. PLUMED automatically
detect which variables are used at every step, leading to better performance when complicated and computationally
expensive variables are monitored - this is not the case here, since the two torsion angles are very fast to compute.
Note that here the work always increase with time and never gets lower which is somewhat surprising if you think
that we are moving in another metastable state. One would expect this to bend and give a signal of approaching a
minimum like before. Nevertheless consider what you we are doing: we are constraining the system in one specific
conformation and this is completely unnatural for a system at 300 kelvin so, even for this small system adopting a
specific conformation in which all the heavy atoms are in a precise position is rather unrealistic. This means that
this state is an high free energy state.
11.12
Belfast tutorial: Metadynamics
11.12.1
Aims
The aim of this tutorial is to introduce the users to running a metadynamics simulation with PLUMED. We will set
up a simple simulation of alanine dipeptide in vacuum, analyze the output, and estimate free energies from the
simulation. We will also learn how to run a well-tempered metadynamics simulation and detect issues related to a
bad choice of collective variables.
Generated by Doxygen
756
11.12.2
Tutorials
Summary of theory
In metadynamics, an external history-dependent bias potential is constructed in the space of a few selected degrees
of freedom ~
s(q), generally called collective variables (CVs) [45]. This potential is built as a sum of Gaussian kernels
deposited along the trajectory in the CVs space:
V (~s, t) =
X
W (kτ ) exp −
d
X
(si − si (q(kτ )))2
i=1
kτ & log &
where -replex 2000 indicates that every 2000 molecular-dynamics steps all replicas are randomly paired (e.g. 0-2
and 1-3) and exchanges are attempted between each pair (as printed in the GROMACS ∗.log files).
The same simulation can be run using WELLTEMPERED metadynamics.
Generated by Doxygen
772
Tutorials
11.14.3.2
Convergence of the Simulations
In the resources for this tutorial you can find the results for a 40ns long Well-Tempered Bias Exchange simulation.
First of all we can try to assess the convergence of the simulations by looking at the profiles. In the "convergence"
folder there is a script that calculates the free energy from the HILLS.0 file at increasing simulation lengths (i.e.
every more 0.8 ns of simulation). The scripts also generate two measures of the evolution of the profiles in time:
1. time-diff.HILLS.0: where it is stored the average deviation between two successive profiles
2. KL.HILLS.0: where it is stored the average deviation between profiles correctly weighted for the free energy
of the profiles themselves (Symmetrized Kullback-Lieber divergence)
From both plots one can deduce that after 8 ns the profiles don't change significantly thus suggesting that averaging
over the range 8-40ns should result in a accurate profile (we will test this using metagui). Another test is that of
looking at the fluctuations of the profiles in a time window instead of looking at successive profiles:
11.14.3.3
Bias-Exchange Analysis with METAGUI
In principle Bias-Exchange Metadynamics can give as a results only N 1D free energy profiles. But the information
contained in all the replicas can be used to recover multidimensional free energy surfaces in >=N dimensions. A
simple way to perform this analysis is to use METAGUI. METAGUI performs the following operations:
1. Clusters the frames in the trajectories on a multidimensional GRID defined by at least the biased coordinates.
2. By using the 1D free energy profiles and the clustering assigns a free energy to the cluster using a WHAM
procedure.
3. Lets the user visualize the clusters.
4. Approximates the kinetics among clusters.
METAGUI (Biarnes et. al) is a plugin for VMD that implements the approach developed by Marinelli et. al 2009. It
can be downloaded from the PLUMED website.
In order for the colvar and hills file to be compatible with METAGUI their header must be formatted as following:
COLVAR.#:
#! FIELDS time cv1 cv2 cv3 cv4
#! ACTIVE 1 1 A
#! ..
...
NOTE:
1. the COLVAR.# files should contain ALL the collective variables employed (all those biased in at least one
replica plus those additionally analyzed). They MUST be named cv1 ... cv
N.theCOLV AR.#f ilesmustbesynchronizedwiththetrajectories, thismeansthatf oreachf rameinthetrajectoryatti
2. a keyword #! ACTIVE NBIASEDCV BIASEDCV LABEL is needed, where NBIASEDCV is the number of biased
collective variables in that replica (not overall), BIASEDCV is the index of the biased collective variables in that
replica (i.e. 1 for the first replica and so on); LABEL is a letter that identify the replica (usually is simply A for the
first, B for the second and so on) this is useful if two replicas are biasing the same collective variable:
Generated by Doxygen
11.14 Belfast tutorial: Replica exchange II and Multiple walkers
COLVAR.0:
#! FIELDS
#! ACTIVE
#! ..
...
COLVAR.1:
#! FIELDS
#! ACTIVE
#! ..
...
COLVAR.2:
#! FIELDS
#! ACTIVE
#! ..
...
COLVAR.3:
#! FIELDS
#! ACTIVE
#! ..
...
773
time cv1 cv2 cv3
1 1 A
time cv1 cv2 cv3
1 2 B
time cv1 cv2 cv3
1 2 C
time cv1 cv2 cv3
0
In the above case Replica 0 biases cv1; replicas 1 and 2 biases cv2 while replica 3 is a neutral (unbiased) replica.
cv3 is unbiased in all the replicas.
The ACTIVE keyword must be the FIRST LINE in the HILLS.# files:
HILLS.#:
#! ACTIVE 1 1 A
#! FIELDS time cv1 sigma_cv1 height biasf
#! ..
...
The above notes hold for the HILLS files as well. In the folder metagui the script check_for_metagui.sh checks
if the header of your file is compatible with METAGUI, but remember that this is not enough! Synchronization of
COLVAR and trajectory files is also needed. HILLS files can be written with a different frequency but times must be
consistent.
NOTE: It is important to copy HILLS files in the metagui folder.
./check_for_metagui.sh ../COLVAR.0
will tell you that the ACTIVE keyword is missing, you need to modify all the header BEFORE proceeding with the
tutorial!!
In the metagui folder there is a metagui.input file:
WHAM_EXE
wham_bemeta.x
BASINS_EXE
kinetic_basins.x
KT 2.4900
HILLS_FILE
HILLS.0
HILLS_FILE
HILLS.1
HILLS_FILE
HILLS.2
HILLS_FILE
HILLS.3
GRO_FILE
VIL.pdb
COLVAR_FILE COLVAR.0 ../traj0.xtc "psi-1"
COLVAR_FILE COLVAR.1 ../traj1.xtc "phi-2"
COLVAR_FILE COLVAR.2 ../traj2.xtc "psi-2"
COLVAR_FILE COLVAR.3 ../traj3.xtc "phi-3"
TRAJ_SKIP 10
CVGRID 1 -3.1415 3.1415 15 PERIODIC
CVGRID 2 -3.1415 3.1415 15 PERIODIC
CVGRID 3 -3.1415 3.1415 15 PERIODIC
CVGRID 4 -3.1415 3.1415 15 PERIODIC
ACTIVE 4 1 2 3 4
T_CLUSTER 0.
T_FILL
8000.
DELTA 4
GCORR 1
TR_N_EXP 5
Generated by Doxygen
774
Tutorials
where are defined the temperature in energy units, the place where to find COLVAR, HILLS and trajectory files. A
reference gro or pdb file is needed to load the trajectories. The definition of the ranges and the number of bins for
the available collective variables.
Now let's start with the analysis:
1. run VMD and load metagui
2. in metagui load the metagui.input file belfast-8-mg1-fig
3. In the left section of the interface "load all" the trajectories
4. Find the Microstates
In order to visualize the microstate it is convenient to align all the structures using the VMD RMSD Trajectory tool
that can be found in Extensions->Analysis.
One or more microstates can be visualized by selecting them and clicking show.
You can sort the microstates using the column name tabs, for example by clicking on size the microstates will be
ordered from the larger to the smaller. If you look at the largest one it is possible to observe that by using the four
selected collective variables the backbone conformation of the peptide is well defined while the side chains can
populate different rotameric states.
The equilibrium time in the analysis panel should be such that by averaging over the two halves of the remind of the
simulation the profiles are the same (i.e the profile averaged between Teq and Teq+(Ttot-Teq)/2 should be the same
of that averaged from Teq+(Ttot-Teq)/2 and Ttot). By clicking on COMPUTE FREE ENERGIES, the program will
first generate the 1D free energy profiles from the HILLS files and then run the WHAM analysis on the microstates.
Once the analysis is done it is possible to visually check the convergence of the 1D profiles one by one by clicking
on the K buttons next to the HILLS.# files. The BLUE and the RED profiles are the two profiles just defined, while
the GREEN is the average of the two. Now it is possible for example to sort the microstates as a function of the free
energy and save them by dumping the structures for further analysis.
If you look in the metagui folder you will see a lot of files, some of them can be very useful:
metagui/MICROSTATES: is the content of the microstates list table metagui/WHAM_RUN/VG_HILLS.#: are the
opposite of the free energies calculated from the hills files metagui/WHAM_RUN/∗.gnp: are gnuplot input files to
plot the VG_HILLS.# files (i.e. gnuplot -> load "convergence..") metagui/WHAM_RUN/FES: is the result of the
WHAM, for each cluster there is its free energy and the error estimate from WHAM
gnuplot> plot [0:40]’FES’ u 2:3
plots the microstate error in the free energy estimate as a function of the microstates free energy. Finally in the
folder metagui/FES there is script to integrate the multidimensional free energy contained in the MICROSTATES
files to a 2D FES as a function of two of the used CV. To use it is enough to copy the MICROSTATES file in FES:
cp MICROSTATES FES/FES.4D
and edit the script to select the two columns of MICROSTATES on which show the integrated FES.
Generated by Doxygen
11.14 Belfast tutorial: Replica exchange II and Multiple walkers
11.14.3.4
775
Multiple Walker Metadynamics
Multiple Walker metadynamics is the simplest way to parallelize a metadynamics calculation: multiple simulation of
the same system are run in parallel using metadynamics on the same set of collective variables. The deposited bias
is shared among the replicas in such a way that the history dependent potential depends on the whole history.
We can use the same common input file defined above and then we can define four metadynamics bias in a similar
way of what was done above for bias-exchange but now all the biases are defined on the same collective variables:
plumed.#.dat
INCLUDE FILE=plumed-common.dat
METAD ...
LABEL=mw
ARG=cv2,cv3
SIGMA=0.3,0.3
HEIGHT=0.2
PACE=100
BIASFACTOR=8
GRID_MIN=-pi,-pi
GRID_MAX=pi,pi
WALKERS_MPI
... METAD
PRINT ARG=cv1,cv2,cv3,cv4 STRIDE=1000 FILE=COLVAR
and the simulation can be run in a similar way without doing exchanges:
mpirun -np 4 gmx_mpi mdrun -s topol -plumed plumed -multi 4
>& log &
alternatively Multiple Walkers can be run as independent simulations sharing via the file system the biasing potential,
this is useful because it provides a parallelization that does not need a parallel code. In this case the walkers read
with a given frequency the Gaussian kernels deposited by the others and add them to their own METAD.
11.14.4
Reference
This tutorial is freely inspired to the work of Biarnes et al.
More materials can be found in
1. Marinelli, F., Pietrucci, F., Laio, A. & Piana, S. A kinetic model of TRP-cage folding from multiple biased
molecular dynamics simulations. PLoS Comput. Biol. 5, e1000452 (2009).
2. Biarnes, X., Pietrucci, F., Marinelli, F. & Laio, A. METAGUI. A VMD interface for analyzing metadynamics and
molecular dynamics simulations. Comput. Phys. Commun. 183, 203–211 (2012).
3. Baftizadeh, F., Cossio, P., Pietrucci, F. & Laio, A. Protein folding and ligand-enzyme binding from biasexchange metadynamics simulations. Current Physical Chemistry 2, 79–91 (2012).
4. Granata, D., Camilloni, C., Vendruscolo, M. & Laio, A. Characterization of the free-energy landscapes of
proteins by NMR-guided metadynamics. Proc. Natl. Acad. Sci. U.S.A. 110, 6817–6822 (2013).
5. Raiteri, P., Laio, A., Gervasio, F. L., Micheletti, C. & Parrinello, M. Efficient reconstruction of complex free
energy landscapes by multiple walkers metadynamics. J. Phys. Chem. B 110, 3533–3539 (2006).
Generated by Doxygen
776
Tutorials
11.15
Belfast tutorial: NMR restraints
11.15.1
Aims
This tutorial is about the use of experimental data, in particular NMR data, either as collective variables or as
replica-averaged restraints in MD simulations. While the first is a just a simple extension of what we have been
already doing in previous tutorials, the latter is an approach that can be used to increase the quality of a force-field
in describing the properties of a specific system.
11.15.1.1
Learning Outcomes
Once this tutorial is completed students will:
• know why and how to use experimental data to define a collective variable
• know why and how to use experimental data as replica-averaged restraints in MD simulations
11.15.2
Resources
The tarball for this project contains the following:
• system: the files use to generate the topol?.tpr files of the first and second example (the setup is for simulations in vacuum)
• first: an example on the use of chemical shifts as a collective variable
• second: an example on the use of chemical shifts as replica-averaged restraints
• third: an example on the use of RDCs (calculated with the theta-method) as replica-averaged restraints
11.15.3
Instructions
11.15.3.1
Experimental data as Collective Variables
In the former tutorials it has been often discussed the possibility of measuring a distance with respect to a structure
representing some kind of state for a system, i.e. Belfast tutorial: Out of equilibrium dynamics. An alternative possibility is to use as a reference a set of experimental data that represent a state and measure the current deviation
from the set. In plumed there are currently implemented the following NMR experimental observables: Chemical
Shifts (only for proteins) CS2BACKBONE, NOE distances, JCOUPLING, PRE intensities, and Residual Dipolar
couplings/pseudo-contact shifts RDC.
In the following we will write the CS2BACKBONE collective variable similar to the one used in Granata et al. (2013)
(while the collective variable is still proportional to the square sum of the deviation of the calculated and experimental
chemical shifts divided by a typical error, the exact definition is not the same. The sum is not done anymore with a
flat bottom difference and the error used are not the one published, so the exact result of the scoring function can
be different).
As a general rule, when using CS2BACKBONE or other experimental restraints it is better to increase the accuracy
of the constraint algorithm due to the increased strain on the bonded structure. In the case of GROMACS it is safer
to use lincs-iter=2 and lincs-order=6.
Generated by Doxygen
11.15 Belfast tutorial: NMR restraints
777
prot: GROUP ATOMS=1-862
cs: CS2BACKBONE ATOMS=prot DATA=data NRES=56 CAMSHIFT
PRINT ARG=cs FILE=COLVAR STRIDE=100
ENDPLUMED
In this case the chemical shifts are those measured for the native state of the protein and can be used, together
with other CVs and Bias-Exchange Metadynamics, to guide the system back and forth from the native structure.
The experimental chemical shifts are in six files inside the "data/" folder (see first example in the resources tarball),
one file for each nucleus. A 0 chemical shift is used where a chemical shift doesn't exist (i.e. CB of GLY) or where it
has not been assigned. Additionally the data folder contains:
• camshift.db: this file is a parameter file for camshift, it is a standard file needed to calculate the chemical
shifts from a structure
• template.pdb: this is a pdb file for the protein we are simulating (i.e. editconf -f conf.gro -o template.pdb)
where atoms are ordered in the same way in which are included in the main code and again it is used to map
the atom in plumed with those in almost.
This example can be executed as
gmx_mpi mdrun -s topol -plumed plumed
11.15.3.2
Replica-Averaged Restrained Simulations
NMR data, as all the equilibrium experimental data, are the result of a measure over an ensemble of structures and
over time. In principle a "perfect" molecular dynamics simulations, that is a simulations with a perfect force-field and
a perfect sampling can predict the outcome of an experiments in a quantitative way. Actually in most of the cases
obtaining a qualitative agreement is already a fortunate outcome. In order to increase the accuracy of a force field
in a system dependent manner it is possible to add to the force-field an additional term based on the agreement
with a set of experimental data. This agreement is not enforced as a simple restraint because this would mean to
ask the system to be always in agreement with all the experimental data at the same time, instead the restraint is
applied over an AVERAGED COLLECTIVE VARIABLE where the average is performed over multiple independent
simulations of the same system in the same conditions. In this way the is not a single replica that must be in
agreement with the experimental data but they should be in agreement on average. It has been shown that this
approach is equivalent to solving the problem of finding a modified version of the force field that will reproduce the
provided set of experimental data without any additional assumption on the data themselves.
The second example included in the resources show how the amber force field can be improved in the case of
protein domain GB3 using the native state chemical shifts a replica-averaged restraint. By the fact that replicaaveraging needs the use of multiple replica simulated in parallel in the same conditions it is easily complemented
with BIAS-EXCHANGE or MULTIPLE WALKER metadynamics to enhance the sampling.
prot: GROUP ATOMS=1-862
cs: CS2BACKBONE ATOMS=prot DATA=data NRES=56
enscs: ENSEMBLE ARG=(cs\.hn_.*),(cs\.nh_.*),(cs\.ca_.*),(cs\.cb_.*),(cs\.co_.*),(cs\.ha_.*)
stcs: STATS ARG=enscs.* SQDEVSUM PARARG=(cs\.exphn_.*),(cs\.expnh_.*),(cs\.expca_.*),(cs\.expcb_.*),(cs\.expco
res: RESTRAINT ARG=stcs.sqdevsum AT=0. KAPPA=0. SLOPE=12
PRINT ARG=(cs\.hn_.*),(cs\.nh_.*),(cs\.ca_.*),(cs\.cb_.*),(cs\.co_.*),(cs\.ha_.*) FILE=CS STRIDE=1000
PRINT ARG=res.bias FILE=COLVAR STRIDE=10
ENDPLUMED
Generated by Doxygen
778
Tutorials
with respect to the case in which chemical shifts are used to define a standard collective variable, in this case
CS2BACKBONE is a collective variable with multiple components, that are all the back calculated chemical shifts,
plus all the relative experimental values. The keyword function ENSEMBLE tells plumed to calculate the average
of the arguments over the replicas (i.e. 4 replicas) and the function STATS compare the averaged back calculated
chemical shifts with the experimental values and calculates the sum of the squared deviation. On this latter number
it is possible to apply a linear RESTRAINT (because the variable is already a sum of squared differences) that is
the new term we are adding to the underlying force field.
This example can be executed as
mpiexec -np 4 gmx_mpi mdrun -s topol -plumed plumed -multi 4
The third example show how RDC (calculated with the theta-methods) can be employed in the same way, in this case
to describe the native state of Ubiquitin. In particular it is possible to observe how the RDC averaged restraint applied
on the correlation between the calculated and experimental N-H RDCs result in the increase of the correlation of
the RDCs for other bonds already on a very short time scale.
RDC ...
GYROM=-72.5388
SCALE=0.001060
ADDCOUPLINGS
LABEL=nh
ATOMS1=20,21 COUPLING1=8.17
ATOMS2=37,38 COUPLING2=-8.271
ATOMS3=56,57 COUPLING3=-10.489
ATOMS4=76,77 COUPLING4=-9.871
#continue....
In this input the first four N-H RDCs are defined.
This example can be executed as
mpiexec -np 8 gmx_mpi mdrun -s topol -plumed plumed -multi 8
11.15.4
Reference
1. Granata, D., Camilloni, C., Vendruscolo, M. & Laio, A. Characterization of the free-energy landscapes of
proteins by NMR-guided metadynamics. Proc. Natl. Acad. Sci. U.S.A. 110, 6817–6822 (2013).
2. Cavalli, A., Camilloni, C. & Vendruscolo, M. Molecular dynamics simulations with replica-averaged structural
restraints generate structural ensembles according to the maximum entropy principle. J. Chem. Phys. 138,
094112 (2013).
3. Camilloni, C., Cavalli, A. & Vendruscolo, M. Replica-Averaged Metadynamics. JCTC 9, 5610–5617 (2013).
4. Roux, B. & Weare, J. On the statistical equivalence of restrained-ensemble simulations with the maximum
entropy method. J. Chem. Phys. 138, 084107 (2013).
5. Boomsma, W., Lindorff-Larsen, K. & Ferkinghoff-Borg, J. Combining Experiments and Simulations Using the
Maximum Entropy Principle. PLoS Comput. Biol. 10, e1003406 (2014).
6. Camilloni, C. & Vendruscolo M. A Tensor-Free Method for the Structural and Dynamical Refinement of Proteins using Residual Dipolar Couplings. J. PHYS. CHEM. B 119, 653 (2015).
Generated by Doxygen
11.16 Belfast tutorial: Steinhardt Parameters
11.16
Belfast tutorial: Steinhardt Parameters
11.16.1
Aims
779
This tutorial is concerned with the collective variables that we use to study order/disorder transitions such as the
transition between the solid and liquid phase. In this tutorial we will look at the transition from solid to liquid as this
is easier to study using simulation. The CVs we will introduce can, and have, been used to study the transition from
liquid to solid. More information can be found in the further reading section.
You will need to ensure that you have compiled PLUMED with the crystallisation module enabled in order
to complete this tutorial. To learn how to activate this module consult the information in the manual about the
List of modules.
11.16.1.1
Learning Outcomes
Once this tutorial is completed students will:
• Know of the existence of the Steinhardt Parameters and know how to create plumed input files for calculating
them.
• Appreciate that the Steinhardt Parameter for a particular atom is a vector quantity and that you can thus
measure local order in a material by taking dot products of the Steinhardt Parameter vectors of adjacent
atoms. Students will know how to calculate such quantities using plumed.
11.16.2
Resources
The tarball for this project contains the following files:
• in : An input file for the simplemd code that forms part of plumed
• input.xyz : A configuration file for Lennard-Jones solid with an FCC solid structure
11.16.3
Instructions
11.16.3.1
Simplemd
For this tutorial we will be using the MD code that is part of plumed - simplemd. This code allows us to do the
simulations of Lennard-Jones that we require here but not much else. We will thus start this tutorial by doing
some simulations with this code. You should have two files from the tarball, the first is called input.xyz and is
basically an xyz file containing the positions of the atoms. The second meanwhile is called in and is the input to
simplemd. If you open the file the contents should look something like this:
inputfile input.xyz
outputfile output.xyz
temperature 0.2
tstep 0.005
friction 1
forcecutoff 2.5
listcutoff 3.0
nstep 50000
nconfig 100 trajectory.xyz
nstat
10 energies.dat
Generated by Doxygen
780
Tutorials
Having run some molecular dynamics simulations in the past it should be pretty obvious what each line of the file
does. One thing that might be a little strange is the units. Simplemd works with Lennard-Jones units so energy is in
units of and length is in units of σ . This means that temperature is in units of kB T , which is why the temperature
in the above file is apparently so low.
Use simplemd to run 50000 step calculations at 0.2, 0.8 and 1.2 kB T . (N.B. You will need an empty file called
plumed.dat in order to run these calculations.) Visualize the trajectory output by each of your simulations using V←MD. Please be aware that simplemd does not wrap the atoms into the cell box automatically. If you are at the tutorial
we have resolved this problem by making it so that if you press w when you load all the atoms they will be wrapped
into the box. At what temperatures did the simulations melt? What then is the melting point of the Lennard-Jones
potential at this density?
11.16.3.2
Coordination Numbers
At the end of the previous section you were able to make very a sophisticated judgement about whether or not the arrangement of atoms in your system was solid-like or liquid-like by simply looking at the configuration. The aim in the
rest of this tutorial is to see if we can derive collective variables that are able to make an equally sophisticated judgement. For our first attempt lets use a CV which we have encountered elsewhere, the COORDINATIONNUMBER.
Rerun the calculations from the previous section but at variance with the previous section use the plumed input file
below instead of a empty file. This input will ensure that the average COORDINATIONNUMBER of the atoms in
your system is computed and printed.
cc: COORDINATIONNUMBER SPECIES=1-108 SWITCH={RATIONAL D_0=1.3 R_0=0.2 D_MAX=3.0} MEAN
PRINT ARG=cc.* FILE=colvar STRIDE=100
Rerun the simplemd simulations described at the end of the previous section. Is the average coordination number
good at differentiating between solid and liquid configurations? Given your knowledge of physics/chemistry is this
result surprising?
11.16.3.3
Steinhardt parameter
The solid and liquid phases of a material are both relatively dense so the result at the end of the last section - the
fact that the coordination number is not particularly good at differentiating between them - should not be that much
of a surprise. As you will have learned early on in your scientific education when solids melt the atoms rearrange
themselves in a much less ordered fashion. The bonds between them do not necessarily break it is just that,
whereas in a the solid the bonds were all at pretty well defined angles to each other, in a liquid the spread of bond
angles is considerably larger. To detect the transition from solid to liquid what we need then is a coordinate that is
able to recognize whether or not the geometry in the coordination spheres around each of the atoms in the system
are the same or different. If these geometries are the same the system is in a solid-like configuration, whereas if
they are different the system is liquid-like. The Steinhardt parameters Q3, Q4 and Q6 are coordinates that allow us
to examine the coordination spheres of atoms in precisely this way. The way in which these coordinates are able to
do this is explained in the video .
Repeat the calculations from the end of the previous section but using the plumed.dat file below.
cc: COORDINATIONNUMBER SPECIES=1-108 SWITCH={RATIONAL D_0=1.3 R_0=0.2 D_MAX=3.0} MEAN
q6: Q6 SPECIES=1-108 SWITCH={RATIONAL D_0=1.3 R_0=0.2 D_MAX=3.0} MEAN
PRINT ARG=cc.*,q6.* FILE=colvar STRIDE=100
This will output the average Q6 parameter and the average COORDINATIONNUMBER. In the Steinhardt parameter
implementation in plumed the set of atoms in the coordination sphere of a particular atom are defined using a
continuous switching function. Is the average Q6 parameter able to differentiate between the solid and liquid states?
Generated by Doxygen
11.16 Belfast tutorial: Steinhardt Parameters
11.16.3.4
781
Local versus Global
At the end of the previous section you showed that the average Q6 parameter for a system of atoms is able to tell
you whether or not that collection of atoms is in a solid-like or liquid-like configuration. In this section we will now
ask the question - can the Steinhardt parameter always, unambiguously tell us whether particular tagged atoms are
in a solid-like region of the material or whether they are in a liquid-like region of the material? This is an important
question that might come up if we are looking at nucleation of a solid from the melt. Our question in this context
reads - how do we unambiguously identify those atoms that are in the crystalline nucleus? A similar question would
also come up when studying an interface between the solid and liquid phases. In this guise we would be asking
about the extent of interface; namely, how far from the interface do we have to go before we can start thinking of the
atoms as just another atom in the solid/liquid phase?
With these questions in mind our aim is to look at the distribution of values for the Q6 parameters of atoms in our
system of Lennard-Jones have. If Q6 is able to unambiguously tell us whether or not an atom is in a solid-like pose
or a liquid-like pose then there should be no overlap in the distributions obtained for the solid and liquid phases.
If there is overlap, however, then we cannot use these coordinates for the applications described in the previous
t
paragraph. To calculate these distributions you will need to run two simulations - one at 0.2 kB T and one at 1.2 kB
using now the following PLUMED input file:
q6: Q6 SPECIES=1-108 SWITCH={RATIONAL D_0=1.3 R_0=0.2 D_MAX=3.0}
hh: HISTOGRAM DATA=q6 GRID_MIN=0 GRID_MAX=1.0 GRID_BIN=100 BANDWIDTH=0.05 STRIDE=100
DUMPGRID GRID=hh FILE=histo STRIDE=50000
Do the distributions of Q6 parameters in the solid and liquid phase overlap?
11.16.3.5
Local Steinhardt parameters
Hopefully you saw that the distribution of Q6 parameters for the solid and liquid phase overlap at the end of the
previous section. Again this is not so surprising - as you go from solid to liquid the distribution of the geometries of
the coordination spheres widens. The system is now able to arrange the atoms in the coordination spheres in a much
wider variety of different poses. Importantly, however, the fact that an atom is in a liquid does not preclude it from
having a very-ordered, solid-like coordination environment. As such in the liquid state we will find the occasional
atom with a high value for the Q6 parameter. Consequently, an ordered coordination environment does not always
differentiate solid-like atoms from liquid-like atoms. The major difference is in the liquid the ordered atoms will
always be isolated. That is to say in the liquid atoms with an ordered coordination will always be surrounded by
atoms with a disordered coordination sphere. By contrast in the solid each ordered atom will be surrounded by
further ordered atoms. This observation forms the basis of the local Steinhardt parameters and the locally averaged
Steinhardt parameters that are explained in this video .
Lets use plumed to calculate the distribution of LOCAL_Q6 parameters in the solid and liquid phases. We can do
this using the input file shown below:
q6: Q6 SPECIES=1-108 SWITCH={RATIONAL D_0=1.3 R_0=0.2 D_MAX=3.0}
lq6: LOCAL_Q6 SPECIES=q6 SWITCH={RATIONAL D_0=1.3 R_0=0.2 D_MAX=3.0}
hh: HISTOGRAM DATA=lq6 GRID_MIN=0 GRID_MAX=1.5 GRID_BIN=150 BANDWIDTH=0.05 STRIDE=10
DUMPGRID GRID=hh FILE=histo STRIDE=50000
Do the distributions of LOCAL_Q6 parameter for the solid and liquid phases overlap?
Lectner and Dellago have designed an alternative to the LOCAL_Q6 parameter that is based on taking the
LOCAL_AVERAGE of the Q6 parameter around a central atom. This quantity can be calculated using plumed.
If you have time try to use the manual to work out how.
Generated by Doxygen
782
Tutorials
11.16.4
Further Reading
There is a substantial literature on simulation of nucleation. Some papers are listed below but this list is far from
exhaustive.
• F. Trudu, D. Donadio and M. Parrinello Freezing of a Lennard-Jones Fluid:
Nucleation to Spinodal Regime , Phys. Rev. Lett. 97 105701 (2006)
From
• D. Quigley and P. M. Rodger A metadynamics-based approach to sampling crystallization
events , Mol. Simul. 2009
• W. Lechner and C. Dellago Accurate determination of crystal structures based on
averaged local bond order parameters J. Chem. Phys 129 114707 (2008)
• B. Cheng, G. A. Tribello and M. Ceriotti Solid-liquid interfacial free energy out of
equilibrium
11.17
Cambridge tutorial
Authors
Max Bonomi and Carlo Camilloni, part of the tutorial is based on other tutorials.
Date
March 4, 2015
This document describes the PLUMED tutorial held for the Computational Biology MPhil, University of Cambridge,
March 2015. The aim of this tutorial is to learn how to use PLUMED to run well-tempered and bias-exchange
simulations and how to run replica-averaged metadynamics to incorporate experimental data into your simulation.
Although the presented input files are correct, the users are invited to refer to the literature to understand how the
parameters of enhanced sampling methods should be chosen in a real application.
Users are also encouraged to follow the links to the full PLUMED reference documentation and to wander around
in the manual to discover the many available features and to do the other, more complete, tutorials. Here we are
going to present only a very narrow selection of methods.
Users are expected to write PLUMED input files based on the instructions below.
11.17.1
Alanine dipeptide: our toy model
In this tutorial we will play with alanine dipeptide (see Fig. cambridge-1-ala-fig). This rather simple molecule is useful
to make many benchmark that are around for data analysis and free energy methods. It is a rather nice example
since it presents two metastable states separated by a high (free) energy barrier. Here metastable states are
intended as states which have a relatively low free energy compared to adjacent conformation. It is conventional
use to show the two states in terms of Ramachandran dihedral angles, which are denoted with Φ and Ψ in Fig.
cambridge-1-transition-fig .
11.17.2
Exercise 1. Metadynamics
11.17.2.1
Resources
The tarball for this project contains all the files needed to run this exercise.
Generated by Doxygen
11.17 Cambridge tutorial
11.17.2.2
783
Summary of theory
In metadynamics, an external history-dependent bias potential is constructed in the space of a few selected degrees
of freedom ~
s(q), generally called collective variables (CVs) [45]. This potential is built as a sum of Gaussian kernels
deposited along the trajectory in the CVs space:
V (~s, t) =
X
W (kτ ) exp −
d
X
(si − si (q(kτ )))2
i=1
kτ & log &
where -replex 10000 indicates that every 10000 molecular-dynamics steps exchanges are attempted (as printed in
the GROMACS ∗.log files).
In order to have an idea of how Bias-Exchange Metadynamics works we can compare the sampling of the four
replicas along the first two collective variables with respect to a free energy surface obtained by sampling in two
dimensions.
The main features are that all the replicas can sample all the relevant free energy minima even if their collective
variable is not meant to sample them, only the replicas with a collective variable meant to pass a barrier can sample
that transition, so high energy regions are sampled only locally. This can seem a weakness in the case of alanine
dipeptide but is the real strength of bias exchange metadynamics, indeed by not knowing anything of a system it is
possible to choose as many collective variables as possible and even if most of them are not particularly useful a
posteriori, they all gain from the good ones and nothing is lost.
Generated by Doxygen
788
11.17.3.4
Tutorials
Calculate free-energies and monitor convergence
As for the former case, one can estimate the free energy as a function of the metadynamics CVs directly from the
metadynamics bias potential. This approach can only be used to recover one-dimensional free-energy profiles:
plumed sum_hills --hills HILLS.0 --mintozero
The command above generates a file called fes.dat in which the free-energy surface as function of phi is calculated
on a regular grid.
It is also possible to calculate one-dimensional free energies from the two-dimensional metadynamics simulation.
For example, if one is interested in the free energy as a function of the phi dihedral alone, the following command
line should be used:
The result should look like this (compared with the one obtained before):
As above we can assess the convergence of a metadynamics simulation by calculating the estimate of the free
energy as a function of simulation time. At convergence, the reconstructed profiles should be similar. The option
–stride should be used to give an estimate of the free energy every N Gaussian kernels deposited, and the option
–mintozero can be used to align the profiles by setting the global minimum to zero. If we use the following command
line:
plumed sum_hills --hills HILLS.0 --stride 500 --mintozero
Try to visualize the different estimates of the free energy as a function of time.
To assess the convergence of the simulation more quantitatively, we can calculate the free-energy difference between the two local minima in the one-dimensional free energy along phi as a function of simulation time. We can
use the bash script analyze_FES.sh to integrate the multiple free-energy profiles in the two basins defined by the
following intervals in phi space: basin A, -31 ns).
Step 3: Run
The simulation should be run until convergence of the four one dimensional free energies, this will typically take
more than 200 ns per replica.
Step 4: Analysis
The user should check the diffusion of the replicas among the biases (see above) and send the converged free
energy profiles.
Step 5: Only for the brave!
The same simulation without experimental restraints could be performed in such a way to compare the free energy
profiles obtained with and without the inclusion of experimental data.
11.18
CINECA tutorial
Authors
Max Bonomi, stealing most of the material from other tutorials. Alejandro Gil Ley is acknowledged for betatesting this tutorial.
Date
November 20, 2015
This document describes the PLUMED tutorial held at CINECA, November 2015. The aim of this tutorial is to learn
how to use PLUMED to analyze molecular dynamics (MD) simulations on-the-fly, to analyze existing trajectories,
and to perform enhanced sampling. Although the presented input files are correct, the users are invited to refer to
the literature to understand how the parameters of enhanced sampling methods should be chosen in a real
application.
Users are also encouraged to follow the links to the full PLUMED reference documentation and to wander around
in the manual to discover the many available features and to do the other, more complete, tutorials. Here we are
going to present only a very narrow selection of methods.
All the tests here are performed on a toy system, alanine dipeptide, simulated in vacuum using the AMBER99SB
force field. Simulations are carried out with GROMACS 5.0.4, which is here assumed to be already patched with
PLUMED 2.2 and properly installed. However, these examples could be easily converted to other MD software.
Generated by Doxygen
11.18 CINECA tutorial
11.18.1
791
Resources
All the GROMACS input files and analysis scripts are provided in this tarball. Users are expected to write
PLUMED input files based on the instructions below.
We can start by downloading the tarball and uncompressing it:
> tar xzvf cineca.tar.gz
Warning
Exercises should be run inside the newly-created cineca directory, by creating new sub-directories, one per
exercise.
11.18.2
Alanine dipeptide: our toy model
In this tutorial we will play with alanine dipeptide (see Fig. cineca-1-ala-fig). This rather simple molecule is useful
to benchmark data analysis and free-energy methods. This system is a nice example because it presents two
metastable states separated by a high free-energy barrier. It is conventional use to characterize the two states in
terms of Ramachandran dihedral angles, which are denoted with Φ and Ψ in Fig. cineca-1-transition-fig .
11.18.3
Monitoring collective variables
The main goal of PLUMED is to compute collective variables, which are complex descriptors of a system than can
be used to analyze a conformational change or a chemical reaction. This can be done either on-the-fly, that is during
MD, or a posteriori, using PLUMED as a post-processing tool. In both cases one should create an input file with a
specific PLUMED syntax. A sample input file is below:
# compute distance between atoms 1 and 10
d: DISTANCE ATOMS=1,10
# create a virtual atom in the center between atoms 20 and 30
center: CENTER ATOMS=20,30
# compute torsional angle between atoms 1,10,20 and center
phi: TORSION ATOMS=1,10,20,center
# print d and phi every 10 step
PRINT ARG=d,phi STRIDE=10
(see DISTANCE, CENTER, TORSION, and PRINT)
PLUMED works using kJ/nm/ps as energy/length/time units. This can be personalized using UNITS. Notice that
variables should be given a name (in the example above, d, and phi), which is then used to refer to these variables.
Lists of atoms should be provided as comma separated numbers, with no space. Virtual atoms can be created
and assigned a name for later use. You can find more information on the PLUMED syntax at Getting Started
page of the manual. The complete documentation for all the supported collective variables can be found at the
Collective Variables page.
Generated by Doxygen
792
Tutorials
11.18.3.1
Exercise 1: on-the-fly analysis
Here we will run a plain MD simulation on alanine dipeptide and compute two torsional angles on-the-fly. GRO←MACS needs a .tpr file, which is a binary file containing initial positions as well as force-field parameters. For this
tutorial, it is sufficient to use the .tpr files provided in the SETUP directory of the package:
• topolA.tpr - setup in vacuum, initialized in state A
• topolB.tpr - setup in vacuum, initialized in state B
However, we also provide .gro, .mdp, and .top files, that can be modified and used to generate a new .tpr file.
GROMACS can be run (interactively) using the following command:
> gmx_mpi mdrun -s ../SETUP/topolA.tpr -nsteps 10000 -x traj.xtc
The nsteps flags can be used to change the number of time steps and topolA.tpr is the name of the tpr file. While
running, GROMACS will produce a md.log file, with log information, and a traj.xtc file, with a binary trajectory. The
trajectory can be visualized with VMD using:
> vmd confout.gro traj.xtc
To activate PLUMED during a GROMACS MD simulation, you need to add the -plumed flag
> gmx_mpi mdrun -s ../SETUP/topolA.tpr -nsteps 10000 -plumed plumed.dat -x traj.xtc
Here plumed.dat is the name of the PLUMED input file. Notice that PLUMED will write information in the md.log
that could be useful to verify if the simulation has been set up properly.
In this exercise, we will run a plain MD simulation and monitor the Φ and Ψ dihedral angles on-the-fly. In order to
do so, you need to prepare the following PLUMED input file:
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
PRINT ARG=phi,psi STRIDE=100 FILE=COLVAR
(see TORSION and PRINT)
PLUMED is going to compute the collective variables only when necessary, that is, in this case, every 100 steps.
This is not very relevant for simple variables such as torsional angles, but provides a significant speed-up when
using expensive collective variables.
PLUMED will write a textual file named COLVAR containing three columns: simulation time, Φ and Ψ. Results can
be plotted using gnuplot:
> gnuplot
# this shows phi as a function of time
gnuplot> plot "COLVAR" u 2
# this shows psi as a function of time
gnuplot> plot "COLVAR" u 3
# this shows psi as a function of phi
gnuplot> plot "COLVAR" u 2:3
Now try to do the same using the two different initial configurations that we provided (topolA.tpr and topol←B.tpr). Results from 200ps (100000 steps) trajectories in vacuum are shown in Figure cineca-ala-traj.
Notice that the result depends heavily on the starting structure. For the simulation in vacuum, the two free-energy
minima are separated by a large barrier so that the system cannot cross it in such short simulation time. Also notice
that the two clouds are well separated, indicating that these two collective variables are appropriate to properly
distinguish the two minima.
As a final comment, consider that if you run twice the same calculation in the same directory, you might overwrite
the output files. GROMACS takes automatic backup of these files, and PLUMED does it as well. In case you are
restarting a simulation, you can add the keyword RESTART at the beginning of the PLUMED input file. This will tell
PLUMED to append files instead of taking a backup copy.
Generated by Doxygen
11.18 CINECA tutorial
11.18.3.2
793
Exercise 2: analysis with the driver tool
Imagine you have already run a simulation, with or without PLUMED. You might want to compute the collective
variables a posteriori, i.e. from the trajectory file. You can do this by using the PLUMED executable on the command
line. Type
> plumed driver --help
to have an idea of the possible options. See driver for the full documentation.
Here we will use the driver the compute Φ and Ψ on the trajectory previously generated. Let's assume the trajectory
is named traj.xtc. You should prepare a PLUMED input file named analysis.dat as:
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
PRINT ARG=phi,psi FILE=COLVAR_ANALYSIS
(see TORSION and PRINT) Notice that typically when using the driver we do not provide a STRIDE keyword to
PRINT. This implies "print at every step" which, analyzing a trajectory, means "print for all the available snapshots".
Then, you can use the following command:
> plumed driver --mf_xtc traj.xtc --plumed analysis.dat
Notice that PLUMED has no way to now the value of physical time from the trajectory. If you want physical time to
be printed in the output file you should give more information to the driver, e.g.:
> plumed driver --mf_xtc traj.xtc --plumed analysis.dat --timestep 0.002 --trajectory-stride 1000
(see driver)
In this case we inform the driver that the traj.xtc file was produced in a run with a timestep of 0.002 ps and
saving a snapshot every 1000 time steps.
You might want to analyze a different collective variable, such as the gyration radius. The gyration radius tells how
extended is a molecule in space. You can do it with the following PLUMED input file
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
heavy: GROUP ATOMS=1,5,6,7,9,11,15,16,17,19
gyr: GYRATION ATOMS=heavy
# the same could have been achieved with
# gyr: GYRATION ATOMS=1,5,6,7,9,11,15,16,17,19
PRINT ARG=phi,psi,gyr FILE=analyze
(see TORSION, GYRATION, GROUP, and PRINT)
Now try to compute the time series of the gyration radius.
Generated by Doxygen
794
11.18.4
Tutorials
Biasing collective variables
We have seen that PLUMED can be used to compute collective variables. However, PLUMED is most often use
to add forces on the collective variables. To this aim, we have implemented a variety of possible biases acting on
collective variables. A bias works in a manner conceptually similar to the PRINT command, taking as argument
one or more collective variables. However, here the STRIDE is usually omitted (that is equivalent to setting it to 1),
which means that forces are applied at every timestep. Starting from PLUMED 2.2 you can change the STRIDE
also for bias potentials, but that's another story. In the following we will see how to build an adaptive bias potential
with metadynamics and how to apply harmonic restraints. The complete documentation for all the biasing methods
available in PLUMED can be found at the Bias page.
11.18.4.1
11.18.4.1.1
Metadynamics
Summary of theory
In metadynamics, an external history-dependent bias potential is constructed in the space of a few selected degrees
of freedom ~
s(q), generally called collective variables (CVs) [45]. This potential is built as a sum of Gaussian kernels
deposited along the trajectory in the CVs space:
V (~s, t) =
X
W (kτ ) exp −
d
X
(si − si (q(kτ )))2
i=1
kτ min && $1min && $1 mpirun -np 4 gmx_mpi mdrun -s topol.tpr -plumed plumed.dat -multi 4 -nsteps 500000
Each of the 4 replicas will open a different topol file, and GROMACS will take care of adding the replica number
before the .tpr suffix. PLUMED deals with the extra number in a slightly different way. In this case, for example,
PLUMED first look for a file named plumed.X.dat, where X is the number of the replica. In case the file is not
found, then PLUMED looks for plumed.dat. If also this is not found, PLUMED will complain. As a consequence,
if all the replicas should use the same input file it is sufficient to put a single plumed.dat file, but one has also
the flexibility of using separate files named plumed.0.dat, plumed.1.dat etc.
Also notice that providing the flag -replex one can instruct GROMACS to perform a replica exchange simulation.
Namely, from time to time GROMACS will try to swap coordinates among neighboring replicas and accept of reject
the exchange with a Monte Carlo procedure which also takes into account the bias potentials acting on the replicas,
even if different bias potentials are used in different replicas. That is, PLUMED allows to easily implement many
forms of Hamiltonian replica exchange.
Generated by Doxygen
11.18 CINECA tutorial
11.18.4.4
11.18.4.4.1
801
Using multiple restraints with replica exchange
Weighted histogram analysis method theory
Let's now consider multiple simulations performed with restraints located in different positions. In particular, we will
consider the i-th bias potential as Vi . The probability to observe a given value of the collective variable s is:
Pi (s) = R
P (s)e
V (s)
BT
ds0 P (s0 )e
−
V (s)
BT
− ki
− ki
P (s)e
=
Zi
Vi (s0 )
kB T
where
X
Zi =
e−(U (q)+Vi (q))
q
The likelyhood for the observation of a sequence of snapshots qi (t) (where i is the index of the trajectory and t
is time) is just the product of the probability of each of the snapshots. We use here the minus-logarithm of the
likelihood (so that the product is converted to a sum) that can be written as
L=−
XZ
dt log Pi (si (t)) =
Vi (si (t))
dt − log P (si (t)) +
+ log Zi
kB T
XZ
i
i
One can then maximize the likelyhood by setting
can be obtained
δL
δP (s)
= 0. After some boring algebra the following expression
V (s)
− ki T
B
δsi (t),s
e
+
dt −
P (s)
Zi
0=
XZ
i
In this equation we aim at finding P (s). However, also the list of normalization factors Zi is unknown, and they
should be found selfconsistently. Thus one can find the solution as
N (s)
P (s) ∝
P R
i
dt e
−
Vi (s)
kB T
Zi
where Z is selfconsistently determined as
Z
Zi ∝
ds0 P (s0 )e
−
Vi (s0 )
kB T
These are the WHAM equations that are traditionally solved to derive the unbiased probability P (s) by the combination of multiple restrained simulations. To make a slightly more general implementation, one can compute the
weights that should be assigned to each snapshot, that turn out to be:
wi (t) ∝ P R
j
1
−βVj (si (t))
dt e Zj
The normalization factors can in turn be found from the weights as
P R
Zi ∝
j
dte−βVi (sj (t)) wj (t)
P R
dtwj (t)
j
This allows to straighforwardly compute averages related to other, non-biased degrees of freedom, and it is thus
a bit more flexible. It is sufficient to precompute this factors w and use them to weight every single frame in the
trajectory.
Generated by Doxygen
802
11.18.4.4.2
Tutorials
Exercise 5
In this exercise we will run multiple restraint simulations and learn how to reweight and combine data with WHAM to
obtain free-energy profiles. We start with running in a replica-exchange scheme 32 simulations with a restraint on
phi in different positions, ranging from -3 to 3. We will instruct GROMACS to attempt an exchange between different
simulations every 1000 steps.
First we need to create the 32 PLUMED input files and .tpr files, using the following script:
nrep=32
dx=‘echo "6.0 / ( $nrep - 1 )" | bc -l‘
for((i=0;iplumed.${i}.dat << EOF
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
#
# Impose an umbrella potential on phi
# with a spring constant of 200 kjoule/mol
# and centered in phi=AT
#
restraint-phi: RESTRAINT ARG=phi KAPPA=200.0 AT=$AT
# monitor the two variables and the bias potential
PRINT STRIDE=100 ARG=phi,psi,restraint-phi.bias FILE=COLVAR
EOF
# we initialize some replicas in A and some in B:
if((i%2==0)); then
cp ../SETUP/topolA.tpr topol$i.tpr
else
cp ../SETUP/topolB.tpr topol$i.tpr
fi
done
And then run GROMACS with the following command:
mpirun -np 32 gmx_mpi mdrun -plumed plumed.dat -s topol.tpr -multi 32 -replex 1000 -nsteps 500000 -x traj.xtc
To be able to combine data from all the simulations, it is necessary to have an overlap between statistics collected
in two adjacent umbrellas.
Have a look at the plots of (phi,psi) for the different simulations to understand what is happening. To visualize them
all at once as in Fig. cineca-usrem-phi-all, you can prepare the following script:
awk ’BEGIN{print ""; ORS=""; print "p \"COLVAR.0\" u 2:3 notitle,"; for(i=1;i<=30;i++) print "\"COLVAR."i"\" u
and then open gnuplot and load it:
gnuplot> load "plot.plt"
An often misunderstood fact about WHAM is that data of the different trajectories can be mixed and it is not necessary to keep track of which restraint was used to produce every single frame. Let's get the concatenated trajectory
trjcat_mpi -cat -f traj*.xtc -o alltraj.xtc
Generated by Doxygen
11.18 CINECA tutorial
803
Now we should compute the value of each of the bias potentials on the entire (concatenated) trajectory.
nrep=32
dx=‘echo "6.0 / ( $nrep - 1 )" | bc -l‘
for i in ‘seq 0 $(( $nrep - 1 ))‘
do
# center of the restraint
AT=‘echo "$i * $dx - 3.0" | bc -l‘
cat >plumed.dat << EOF
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
restraint-phi: RESTRAINT ARG=phi KAPPA=200.0 AT=$AT
# monitor the two variables and the bias potential
PRINT STRIDE=100 ARG=phi,psi,restraint-phi.bias FILE=ALLCOLVAR.$i
EOF
plumed driver --mf_xtc alltraj.xtc --trajectory-stride=10 --plumed plumed.dat
done
It is very important that this script is consistent with the one used to generate the multiple simulations above. Now,
single files named ALLCOLVAR.XX will contain on the fourth column the value of the bias centered in a given
position, computed on the entire concatenated trajectory.
Next step is to compute the weights self-consistently solving the WHAM equations, using the python script "wham.←py" contained in the SCRIPTS directory. We will run this script as follows:
bash ../SCRIPTS/wham.sh ALLCOLVAR.*
This script will produce several files. Let's visualize "phi_fes.dat", which contains the free energy as a function of
phi, and compare this with the result previously obtained with metadynamics.
11.18.4.4.3
Exercise 6
In the previous exercise, we use multiple restraint simulations to calculate the free energy as a function of the
dihedral phi. The resulting free energy was in excellent agreement with our previous metadynamics simulation. In
this exercise we will repeat the same procedure for the dihedral psi. At the end of the steps defined above, we can
plot the free energy "psi_fes.dat" and compare it with the profile calculated from a metadynamics simulations using
both phi and psi as CVs.
We can easily spot from the plot above that something went wrong in this multiple restraint simulations, despite we
used the very same approach we adopted for the phi dihedral. The problem here is that psi is a "bad" collective
variable, and the system is not able to equilibrate the missing slow degree of freedom phi in the short time scale of
the umbrella simulation (1 ns). In the metadynamics exercise in which we biased only psi, we detect problems by
observing the behavior of the CV as a function of simulation time. How can we detect problems in multiple restraint
simulations? This is slightly more complicated, but running this kind of simulation in a replica-exchange scheme
offers a convenient way to detect problems.
The first thing we need to do is to demux the replica-exchange trajectories and reconstruct the continous trajectories
of the replicas across the different restraint potentials. In order to do so, we can use the following script:
demux.pl md0.log
trjcat_mpi -f traj?.xtc traj??.xtc
-demux replica_index.xvg
This commands will generate 32 continous trajectories, named XX_trajout.xtc. We will use the driver to calculate
the value of the CVs phi and psi on these trajectories.
Generated by Doxygen
804
Tutorials
nrep=32
for i in ‘seq 0 $(( $nrep - 1 ))‘
do
cat >plumed.dat << EOF
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
# monitor the two variables
PRINT STRIDE=100 ARG=phi,psi FILE=COLVARDEMUX.$i
EOF
plumed driver --mf_xtc ${i}_trajout.xtc --trajectory-stride=10 --plumed plumed.dat
done
The COLVARDEMUX.XX files will contain the value of the CVs on the demuxed trajectory. If we visualize these
files (see previous exercise for instructions) we will notice that replicas sample the CVs space differently. In order
for each umbrella to equilibrate the slow degrees of freedom phi, the continuous replicas must be ergodic and thus
sample the same distribution in phi and psi.
11.19
Using Hamiltonian replica exchange with GROMACS
When patching GROMACS with PLUMED, it is also possible to perform Hamiltonian replica exchange with different
topologies. Although this feature is provided together with PLUMED, it is actually a new feature for GROMACS itself
that can be enabled using the -hrex flag of mdrun. This implementation is very close to the one used to produce
the data in this paper [105]. In case you find it useful, please cite this paper.
Warning
This feature is currently used by several groups and should be robust enough. However, be sure that you
understand its limitations and to perform all the tests discussed in this page before using it in production.
In this short tutorial you will learn how to do two things:
• Generate scaled topologies with plumed partial_tempering. This is actually not directly related to
the -hrex flag.
• Run GROMACS with replica exchange and multiple topologies.
11.19.1
Generate scaled topologies
Plumed comes with a partial_tempering command line tool that can be used to generate scaled topologies.
Notice that you might want to generate these topologies by yourself. This step is totally independent from the use
of the -hrex flag.
The partial_tempering tool can be invoked as follows:
plumed partial_tempering scale < processed.top
where scale is the Hamiltonian scaling factor and processed.top is a post-processed topology file (i.e. produced
with grompp -pp) where each "hot" atom has a "_" appended to the atom type, e.g. change this
Generated by Doxygen
11.19 Using Hamiltonian replica exchange with GROMACS
1
805
HC
1
ACE
HH31
1
0.1123
1.008
; qtot 0.1123
HC_
1
ACE
HH31
1
0.1123
1.008
; qtot 0.1123
to this:
1
Notice that the section that should be edited is the [atoms] section for all the molecules that you wish to affect
(typically only for the solute, but you may also want to change solvent parameters). If you select all the atoms of the
solute, you will be able to prepare topologies such as those needed in a REST2 simulation [104].
Also remember to first produce the processed.top file with grompp -pp. Editing a normal topol.top file will not work,
because it does not contain all the parameters. The processed.top file should not have any "#include" statement.
# produce a processed topology
grompp -pp
# choose the "hot" atoms
vi processed.top
# generate the actual topology
plumed partial_tempering $scale < processed.top > topol$i.top
Warnings:
• It's not very robust and there might be force-field dependent issues!
• It certainly does not work with CHARMM cmap
Suggested tests:
1. Compare partial_tempering with scale=1.0 to non-scaled force field. E.g.
grompp -o topol-unscaled.tpr
grompp -pp
vi processed.top # choose the "hot" atoms appending "_". You can choose whatever.
plumed partial_tempering 1.0 < processed.top > topol-scaled.top # scale with factor 1
grompp -p topol-scaled.top -o topol-scaled.tpr
# Then do a rerun on a trajectory
mdrun -s topol-unscaled.tpr -rerun rerun.trr
mdrun -s topol-scaled.tpr -rerun rerun.trr
# and compare the resuling energy files. they should be identical
2. Compare partial_tempering with scale=0.5 to non-scaled force field. Repeat the same procedure but using
"plumed partial_tempering 0.5". Choose all the atoms in all the relevant [atoms] sections (e.g. solute, solvent
and ions). In the two resulting energy files you should see: long range electrostatics, LJ, and dihedral energy
is half in the scaled case all other terms (bonds/bends) are identical.
11.19.2
Run GROMACS
If GROMACS has been patched with PLUMED it should accept the -hrex option in mdrun. Please double check this
(mdrun -h should list this possibility). Notice that not all the versions of GROMACS allow this feature. First of all
prepare separate topologies for each replicas using plumed partial_tempering tool as shown above (or
using some other tool). Then run a normal replica exchange with gromacs adding the flag "-hrex" on the command
line.
A complete run script could be adapted from the following
Generated by Doxygen
806
Tutorials
# five replicas
nrep=5
# "effective" temperature range
tmin=300
tmax=1000
# build geometric progression
list=$(
awk -v n=$nrep \
-v tmin=$tmin \
-v tmax=$tmax \
’BEGIN{for(i=0;i topol$i.top
# prepare tpr file
# -maxwarn is often needed because box could be charged
grompp_mpi_d -maxwarn 1 -o topol$i.tpr -f grompp$i.mdp -p topol$i.top
done
mpirun -np $nrep gmx_mpi mdrun_d -v -plumed plumed.dat -multi $nrep -replex 100 -nsteps 15000000 -hrex
Notice that total cell could be charged. This happens whenever the scaled portion of the system is not neutral.
There should be no problem in this. When used with pbc, GROMACS will add a compensating background.
Suggested check:
• Try with several identical force fields (hard code the same lambda for all replicas in the script above) and
different seed/starting point. Acceptance should be 1.0
Notice that when you run with GPUs acceptance could be different from 1.0. The reason is that to compute the
acceptance GROMACS is sending the coordinates to the neighboring replicas which then recompute energy. If
all the tpr files are identical, one would expect energy to be identically to the originally computed one. However,
calculations made with GPUs are typically not reproducible to machine precision. For a large system, even an
error in the total energy for the last significant digit could be on the order of a kJ. This results in practice in a lower
acceptance. The error induced on the final ensemble is expected to be very small.
Warnings:
• Topologies should have the same number of atoms, same masses and same constraint topology. Some of
these differences (e.g. masses) are not explicitly checked and might lead to unnoticed errors in the final
results.
• Choose neighbor list update (nstlist) that divides replex. Notice that running with GPUs GROMACS is going
to change nstlist automatically, be sure that it still divides replex.
• Option -hrex requires also option -plumed. If you do not care about plumed, just provide an empty plumed.dat
file.
• It should work correctly if replicas have different force-field, temperature, lambda, pressure, in any combination. However, not all these combinations have been tried in practice, so please first test the code on a system
for which you know the result.
Generated by Doxygen
11.20 Julich tutorial: Developing CVs in plumed
11.20
Julich tutorial: Developing CVs in plumed
11.20.1
Aims
807
The aim of this tutorial is to introduce users to the tutorials in the developer manual of PLUMED. We will learn a
little bit about the structure of the code and how this structure can be visualized using the tree diagrams in the
developer manual. You will then learn how to implement a new collective variable in a way that uses as much of the
functionality that is already within the code and that thus avoids the duplication of code. Finally, you will learn how
to write regression tests and how these can be used for continuous integration.
11.20.2
Learning Outcomes
By the end of this session you will know how to:
• access the developer manual for PLUMED.
• find the tutorial information for implementing new collective variables, multicolvars, functions, biases and
analysis routines.
- find the tree diagrams showing the class structure in the PLUMED developer manual.
• exploit the functionality within PLMD::multicolvar in order to write a reasonably complex collective
variable quickly.
• write regression tests for PLUMED and understand how these are used for continuous integration.
To do this module you must understand the basics of object-oriented programming. Information on object oriented
programming and how it is used within plumed can be found here .
11.20.3
Resources
The tarball for this project contains the following directories:
• rt-coord : a directory containing input files for doing a regtest on an already existing collective variable.
• rt-second-shell : a directory containing input files for doing a regtest on the collective variable you will implement within this tutorial
At the start of the exercise you should move these two directories to the plumed2/regtest/multicolvar directory of
your PLUMED source. You should see many other directories called rt... within the same directory. If you change
into any of these directories and issue the following set of commands:
source ../../../sourceme.sh
make
Then you will have run one of the regression tests of PLUMED. If the test runs without a hitch you should get an
output something like this:
../../scripts/run
Thu Aug 20 14:33:00 IST 2015
Running regtest in /Users/gareth/Projects/CVception/plumed2/regtest/multicolvar/rt22
cp: ../tmp is a directory (not copied).
++ Test type: driver
++ Arguments: --plumed plumed.dat --trajectory-stride 10 --timestep 0.005 --ixyz trajectory.xyz --dump-forces
++ Processors: 0
/Users/gareth/Projects/CVception/plumed2/regtest/multicolvar/rt22/tmp
Run driver
Done. Here is the error file:
Generated by Doxygen
808
11.20.4
Tutorials
Introduction
PLUMED has two manuals: a manual that is for users of the code and a manual that is for developers of the code.
If you are interested in implementing new features in the code your first point of call should thus be the developer
manual, which can be found here . Alternatively, you can get to the front page of the developer manual by clicking
the USER/DEVELOPER logo in the top right hand corner of any page of the user manual.
One of nicest features of PLUMED for the developer is that all the code and documentation for any new PLUMED
command all appears together in a single file. When you come to implement a new feature it is thus relatively
unlikely that you will have to modify any of the files you downloaded. Adding a new feature is simply a matter of
adding one further cpp file containing the new method and the documentation for this method. We are able to
achieve this by exploiting abstract base classes and polymorphism. All classes that calculate collective variables,
print these variables or calculate biases thus inherit from a single base class called Action. You can read about
the Action class here . Notice also that this page also shows how all the various classes within the code inherit
from this single base class. It is perhaps worth spending a little while browsing through the various branches of
this tree and understanding how the classes at each level become increasingly specialized and thus fit for particular
purposes.
Lets say you want to implement a new collective variable in PLUMED. One way to start this task would be to write a
new class that inherits from the PLMD::Colvar base class.
If you click on the box in the tree for PLMD::Colvar and follow various links on the various subject pages you
will eventually get to the following page , which will give you a step-by-step set of instructions for implementing a
new collective variable. If you look through the manual you can find similar pages that provide you with instructions
for implementing new analysis methods, functions and so on. Our suggestion when you implement something new
would thus be to find some similar functionality in the code, look at how it is implemented and to look in the developer
manual at the descriptions of the classes that have been inherited. This process is what we will try and take you
through in this short tutorial.
11.20.5
Instructions
11.20.5.1
Calculating a reasonably complex collective variable
In this first exercise I would like you to look through the manual and work out how to use the functionality that is
already available in PLUMED to calculate the following collective variable:
s=
108
X
1−
i=1
1−
1−
ci 6
4
ci 12
4
where ci is equal to the coordination number of atom i, i.e.:
ci =
X 1−
j6=i
1−
rij 6
1
rij 12
1
So rij is the distance between atom i and atom j . This collective variable measures the number of coordination
numbers that are more than 4 so the summations in the above expressions run over all 108 atoms in this particular
system.
Write an input file that computes s and outputs its value to a file called colvar and that computes both the analytical
and numerical derivatives of s and outputs this information to a file called deriv. You are going to run this calculation
in the rt-coord directory that you downloaded with the tarball for this exercise so you should create this input file
within that directory. You will need to output the quantities in the colvar and deriv files with only four decimal places.
When you are content with your input run the calculation by typing make. If you have done everything correctly you
should see the output that was discussed above.
In setting up your input files you may find it useful to watch our introductory video and this video on
some of the features that are available in the code. Obviously, the user manual will be indispensable as well.
Generated by Doxygen
11.20 Julich tutorial: Developing CVs in plumed
11.20.5.2
809
Implementing a new collective variable
In this second exercise I would like you to implement the following collective variable:
s=
108 Z
X
i=1
59
57
(xi − x)2
exp −
2
dx
where xi is number of atoms in the second coordination sphere of the ith atom, i.e.:
s=
XZ
i6=j
4
2
(rij − r)2
exp −
dr
2
So rij is the distance between atom i and atom j . This collective variable measure the number of atoms that have
between 57 and 59 atoms in their second coordination sphere. There are a number of observations we can make
here that will help you enormously:
• Notice that CV is similar to the coordination number CV you calculated in the first example. For both CVs
there is a sum over a quantity that is calculated for different sets of atoms. You should thus look at what was
done by the routines that calculate the first CV and see what you can reuse.
• Notice that with the first CV we can calculate the number of coordination numbers that are within a certain
range as well as the number of coordination numbers that are less than a certain threshold.
• You can set the link cell cutoff equal to
std::numeric_limits::max()
• Lastly, this tool will prove very useful.
Write an input file that computes s and outputs its value to a file called colvar and that computes both the analytical
and numerical derivatives of s and outputs this information to a file called deriv. When outputting numbers to
colvar and deriv you should output numbers to four and three decimal places respectively. You are going to run
this calculation in the rt-second-shell directory that you downloaded with the tarball for this exercise so you should
create this input file within that directory. When you are content with your input run the calculation by typing make.
If you have done everything correctly you should see the output that was discussed above.
If you have sufficient time try use doxygen within PLUMED to write the documentation for your new collective
variable.
Generated by Doxygen
810
Tutorials
11.20.6
Final thoughts
The aim of this tutorial is not so much to implement the CV. I do not think it is a particularly interesting or useful CV.
Instead the hope is that by doing it you will get some idea of how to implement things within PLUMED. Based on
my experience there are three key things I wish I could go back and tell my younger self about programming, which
I would urge you to learn now:
• Write less code The more code you write the more bugs you generate. To be totally clear this is not me
trying to say I am better at coding than you are - the same statement holds true if I replace each you in the
above with an I - it holds true for everyone. In addition, there are lots of smart people out in the world writing
code (and again I am not talking about the developers of plumed). Their code is properly tested and faster
than anything that you will write so spend your time learning how it works so that you can re-use it.
• Test your code Notice that I set up directories that you could use to test your code for this tutorial. Testing
should always be part of your development workflow and coming up with ways to test your code is hard, which
is why we often don't do it enough. Also don't develop stuff in a vacuum get in touch with people who are
using the code. You need to test your code on systems that people actually want to simulate and not just on
dummy problems. In addition, you should learn to use profiling tools such as Valgrind and instruments on
the mac so that you can find memory leaks and bottlenecks in your code. When you start doing this properly
you will realize that you cannot possibly properly maintain all the code that you have written and you will see
clearly that you that you need to write less code.
• Write documentation for your code Undocumented software is useless. You need to explain how to use
your code and to fill your manual with examples of how the code can be used to solve specific and interesting
problems. That is to say that you need to provide examples of calculations that users actually want to perform.
To be clear here writing a manual that tells users how something like the shake algorithm works in general
terms is actually pretty useless. After all a user can go off and find out this information from a textbook, you
could thus replace your description with a link to a textbook. What users want from you is an example that is
similar to the calculation they actually want to set up. If I were providing documentation for an implementation
of shake in an MD code I would thus explain in detail how to set up shake to constrain all the angles and
bonds in all the water molecules in my system as it is a fair bet that this is how it will be being used by many
users.
I hope you have seen from this tutorial that PLUMED tries to help you with all of these aims. We have a developer
manual where we try to explain how to use the code that is already there. In addition, you can quite quickly generate
nicely formatted user documentation for new CVs and it is easy to add new regression tests that allow you to test
new features. Notice also that whenever commits are made on the origin git repository we use a website called
travis-ci to test that the code works across a range of platforms.
11.21
Lugano tutorial: Analyzing CVs
11.21.1
Aims
The aim of this tutorial is to introduce you to the PLUMED syntax. We will go through the writing of input files to
calculate and print simple collective variables. We will then discuss how we can use PLUMED to analyze a trajectory
by calculating ensemble averages, histograms and free energy surfaces.
Generated by Doxygen
11.21 Lugano tutorial: Analyzing CVs
11.21.2
811
Learning Outcomes
Once this tutorial is completed students will:
• Know how to write PLUMED input files that can be used to calculate and print collective variables.
• Be able to calculate a collective variable that take the position of center of mass as input.
• Know how to write a PLUMED input file that can be used to calculate an ensemble average.
• Know how to write a PLUMED input file that can be used to calculate a histogram. Students will also learn
how this histogram can be converted into a free energy surface.
11.21.3
Resources
The tarball for this project contains the following files:
• trajectory-short.xyz : a (short) trajectory for a 16 residue protein in xyz format. All the calculations with plumed
driver that will be performed during this tutorial will use this trajectory.
• template.pdb : a single frame from the trajectory that can be used in conjunction with the MOLINFO command
• in : An input file for the simplemd code that forms part of PLUMED
• input.xyz : A configuration file for Lennard-Jones solid with an FCC solid structure
11.21.4
Instructions
PLUMED2 is a library that can be incorporated into many MD codes by adding a relatively simple and well documented interface. Once it is incorporated you can use PLUMED2 to perform a variety of different analyzes on the fly
and to bias the sampling in the molecular dynamics engine. PLUMED2 can also, however, be used as a standalone
code for analyzing trajectories. If you are using the code in this way you can, once PLUMED2 is compiled, run the
plumed executable by issuing the command:
plumed
Let's start by getting a feel for the range of calculations that we can use PLUMED2 to perform. Issue the following
command now:
plumed --help
What is output when this command is run is a list of the tasks you can use PLUMED2 to perform. There are commands that allow you to patch an MD code, commands that allow you to run molecular dynamics and commands
that allow you to build the manual. In this tutorial we will mostly be using PLUMED2 to analyze trajectories, however.
As such most of the calculations we will perform will be performed using the driver tool. Let's look at the options we
can issue to plumed driver by issuing the following command:
plumed driver --help
As you can see we can do a number of things with plumed driver. For all of these options, however, we are going
to need to write a PLUMED input file. Before we get on to writing input files for PLUMED there is information
Codes interfaced with PLUMED here which provides details on what the other PLUMED2 tools do and instructions
for how to interface PLUMED with an MD code. You may like to look at this information now or you might prefer to
return after you have finished the exercises here.
Generated by Doxygen
812
Tutorials
11.21.4.1
PLUMED2's internal units
By default the PLUMED inputs and outputs quantities in the following units:
• Energy - kJ/mol
• Length - nanometers
• Time - picoseconds
If you want to change these units you can do this using the UNITS keyword.
11.21.4.2
Introduction to the PLUMED input file
Many input files for PLUMED provides specifications for one or more CVs. These specifications are then followed
by an instruction to PLUMED to PRINT these CVs and a termination line. Comments are denoted with a # and
the termination of the input for PLUMED is marked with the keyword ENDPLUMED. Any words that follow the E←NDPLUMED line are ignored by PLUMED. You can also introduce blank lines as these will not be interpreted by
PLUMED.
The following input can be used analyze the DISTANCE between the two terminal carbons of a 16 residues peptide.
The PRINT command after the DISTANCE command ensures that the results (i.e. the distances calculated) are
printed into the file named COLVAR.
#my first PLUMED input:
e2edist: DISTANCE ATOMS=2,253
#printout frequency
PRINT ARG=e2edist STRIDE=1 FILE=COLVAR
#endofinput
ENDPLUMED
here I can write what I want it won’t be read.
Let's use this simple input file to analyze the trajectory included in the RESOURCES. To do so copy the input above
into a file called plumed.dat and then issue the command below:
plumed driver --plumed plumed.dat --ixyz trajectory-short.xyz --length-units 0.1
Notice the –length-units 0.1 flag here. This tells PLUMED to convert the positions in the xyz file here, which are in
Angstroms, into nm, which remember are PLUMED2's internal units
When this command finishes running you should have a file called COLVAR. If you look at it's contents (using the
command more COLVAR for instance) you will find that the first two lines read:
#! FIELDS time e2edist
0.000000 2.5613161
The first line of the COLVAR files tells you what values are in each of the columns. The remaining lines then tell you
the values these quantities took in the various trajectory frames. We can plot this data using gnuplot (or our favorite
graphing program) by issuing the following commands:
gnuplot
p ’COLVAR’ u 1:2 w l
What this graph shows is the value of the distance that we calculated using PLUMED as a function of time. As you
can see the distance fluctuates about as the atoms in our system move about in accordance with the various forces
that act upon them.
Right so hopefully that wasn't too hard. What we are going to next is we are going to try to understand the input file
that we have written a bit better.
Generated by Doxygen
11.21 Lugano tutorial: Analyzing CVs
11.21.4.3
813
The PLUMED input syntax
The input file that we issued in the last section looked something like this:
e2edist: DISTANCE ATOMS=2,253
PRINT ARG=e2edist STRIDE=1 FILE=COLVAR
What happens if we reverse the order of the two commands in the input file. In other words, what would have
happened if we had run with an input file that looked like this:
PRINT ARG=e2edist STRIDE=1 FILE=COLVAR
e2edist: DISTANCE ATOMS=2,253
Run the input file above using the commands described in the previous section to find out.
If everything is working correctly the input above should crash with the following error message:
+++ Internal PLUMED error
+++ file Action.cpp, line 234
+++ message: ERROR in input to action PRINT with label @0 : cannot find action named e2edist (hint! the action
Take a moment to read that error message and to try to think what it might mean before reading on.
To understand the error lets look at the correct input again:
e2edist: DISTANCE ATOMS=2,253
PRINT ARG=e2edist STRIDE=1 FILE=COLVAR
You should think of the PLUMED input syntax as a kind of scripting language with commands and variables. The
first line in the above file thus tells PLUMED to calculate the distance between atoms 2 and 253 and to store the
value of this distance in a variable called e2edist . The fact that this quantity is stored in a variable is important
as it ensures that we can access this quantity when we come to issue commands later in the input file. So in the
second line above we print a quantity. What quantity should be printed? e2edist - the distance between atom 2 and
atom 253. Easy!
So why does the second input, that has the order of these two commands reversed, not work? Well the variable
e2edist has to be defined before it can be used because in PLUMED2 the commands are executed in the same
order as they are defined in the input file. We thus cannot do anything with e2edist (i.e. PRINT it) without first
explaining how it is calculated.
This input demonstrates the key idea of the PLUMED syntax. Quantities calculated by commands such as
DISTANCE are given labels (e2edist) so that they can be reused when performing other commands. This idea
is discussed in more depth in the following video https://www.youtube.com/watch?v=PxJP16qNC←Ys.
If you understand this idea though you are 90% of the way to understanding how to used PLUMED. Well done.
Generated by Doxygen
814
11.21.4.4
Tutorials
Center of mass positions
When calculating many collective variables it is useful to not think in terms of calculating them directly based on the
positions of a number of atoms. It is useful to instead think of them as being calculated from the position of one or
more virtual atoms whose positions are generated based on the position of a collection of other atoms. For example
you might want to calculate the distance between the center of masses of two molecules. In this case it is useful
to calculate the two positions of the centers of mass first and to then calculate the distance between the centers of
mass. The PLUMED input that you would use for such a calculation reflects this way of thinking. An example of a
PLUMED input that can be used to perform this sort of calculation is shown below:
first: CENTER ATOMS=1,2,3,4,5,6
last: CENTER ATOMS=251-256
e2edist: DISTANCE ATOMS=2,253
comdist: DISTANCE ATOMS=first,last
PRINT ARG=e2edist,comdist STRIDE=1 FILE=COLVAR
ENDPLUMED
Make a PLUMED input containing the above input and execute it on the trajectory that you downloaded at the start
of the exercise by making use of the commands in section Introduction to the PLUMED input file
Before we turn to analyzing what is output from this calculation there are a few things to note about this input file.
Firstly, I should describe what this file instructs PLUMED to do. It tells PLUMED to:
1. calculate the position of the Virtual Atom 'first' as the CENTER of atoms from 1 to 6;
2. calculate the position of the Virtual Atom 'last' as the CENTER of atoms from 251 to 256;
3. calculate the distance between atoms 2 and 253 and saves it in 'e2edist';
4. calculate the distance between the two atoms 'first' and 'last' and saves it in 'comdist';
5. print the content of 'e2edist' and 'comdist' in the file COLVAR
Notice that in the input above we have used two different ways of writing the atoms used in the CENTER
calculation:
1. ATOMS=1,2,3,4,5,6 is the explicit list of the atoms we need
2. ATOMS=251-256 is the range of atoms needed
Notice also that ranges of atoms can be defined with a stride which can also be negative as shown by the commands
below, which are both equivalent:
1. ATOMS=from,to:by (i.e.: 251-256:2)
2. ATOMS=to,from:-by (i.e.: 256-251:-2)
Lets now return to the business of analyzing what was output by the calculation. Lets begin by looking at the
contents of the COLVAR file that was output. When you do so you should find that the first few lines of this file read:
#! FIELDS time e2edist comdist
0.000000 2.516315 2.464043
Generated by Doxygen
11.21 Lugano tutorial: Analyzing CVs
815
Notice that at variance with the file that was output in the previous section we now have three columns of numbers
in the output file. Given the PRINT command that we used in the input to this calculation though this new behavior
makes a lot of sense.
Lets now plot contents of the COLVAR file so we can compare the behavior of the distance between the two terminal
carbons and the distance between the centers of the mass of the two terminal residues in this trajectory (these two
distances are what the above input is calculating). To plot this data issue the following commands:
gnuplot
p ’COLVAR’ u 1:2 w l, ’’ u 1:3 w l
Given what you observe for the behavior of these two distance what do you now expect to see in the trajectory?
Let's look at the trajectory to see if we are right. To look at the trajectory issue the following commands:
vmd template.pdb trajectory-short.xyz
Lets summarize what we have learned from these sections thus far. We have seen that:
• PLUMED provides a simple syntax that can be used to calculate the DISTANCE between any pair of atoms
in our system.
• PLUMED also allows us to calculate the positions of virtual atom (e.g. CENTER) and that we can calculate
the DISTANCE between these quantities.
• Calculating these quantities is useful because it allows us to simplify the high-dimensional information contained in a trajectory.
Now, obviously, PLUMED can do much more than calculate the distances between pairs of atoms as we will start
to see that in the following sections.
11.21.4.5
Calculating torsion angles
In the previous sections we have seen how we can use PLUMED to calculate distances and how by plotting these
distances we can begin to simplify the high dimensional data contained in a trajectory. Obviously, calculating a
DISTANCE is not always the best way to simplify the information contained in a trajectory and we often find we
have to work with other more-complex quantities. PLUMED thus started as a library that was used to gather all
the various implementations people had written for different collective variables (CVs) that people had used to
"analyze" trajectories over the years (analyze is in inverted commas here because, as you will see if you continue
to use PLUMED, we use CVs to do much more than simply analyze trajectories).
Now we will not have time to go over all the quantities that can be calculated in this tutorial. Once you understand
the basic principles, however, you should be able to use the manual to work out how to calculate other quantities
of interest. With this in mind then lets learn how to calculate a TORSION. As with DISTANCE the atoms that we
specify in our TORSION command can be real or virtual. In the example below two real atoms and a virtual atom
are used:
first: CENTER ATOMS=1-6
last: CENTER ATOMS=251-256
cvtor: TORSION ATOMS=first,102,138,last
PRINT ARG=cvtor STRIDE=1 FILE=COLVAR
ENDPLUMED
Generated by Doxygen
816
Tutorials
Copy this input to a PLUMED input file and use it to analyze the trajectory you downloaded at the start of this
exercise by using the commands described in section Introduction to the PLUMED input file then plot the CV output
using gnuplot.
As you can hopefully see calculating TORSION values and other CVs is no more difficult than calculating DISTANCE
values. In fact it is easier as generally when you calculate the torsion angles of a protein you often wish to calculate
particular, named torsion angles (i.e. the φ and ψ angles). The MOLINFO command makes it particularly easy to
do this. For instance suppose that you want to calculate and print the φ angle in the sixth residue of the protein and
the ψ angle in the eighth residue of the protein. You can do so using the following input:
MOLINFO STRUCTURE=template.pdb
phi6: TORSION ATOMS=@phi-6
psi8: TORSION ATOMS=@psi-8
PRINT ARG=phi6,psi8 FILE=colvar
Copy this input to a PLUMED input file and use it to analyze the trajectory you downloaded at the start of this
exercise by using the commands described in section Introduction to the PLUMED input file then plot the CV output
using gnuplot. Notice that you will need the template.pdb file you downloaded at the start of this exercise in order
for this to run.
11.21.4.6
An exercise with the radius of gyration
Lets now see if you can use everything you have learned to setup a PLUMED input file of your own. What I would
like you to do is to write a PLUMED input file that measures the Radius of Gyration GYRATION for the configurations
in each of the frames in the trajectory that you downloaded at the start of this exercise. This radius of gyration will
be calculated using the positions of all the atoms in that trajectory.
NOTE: if what you need for one or more variables is a long list of atoms and not a virtual atom you can use the
keyword GROUP. A GROUP can be defined using ATOMS in the same way we saw before, in addition it is also
possible to define a GROUP by reading a GROMACS index file.
ca: GROUP ATOMS=9,16,31,55,69,90,102,114,124,138,160,174,194,208,224,238
Now 'ca' is not a virtual atom but a simple list of atoms.
11.21.4.7
Coordination numbers
In the previous sections we have learned how PLUMED can be used to calculate simple functions of atomic
positions such as the DISTANCE between pairs of atoms. As discussed here (https://www.youtube.←com/watch?v=iDvZmbWE5ps) many of the more complicated collective variables that we use to analyze simulations can be calculated by computing these simple quantities multiple times for different sets of atoms. That is to
say we can calculate many more complicated collective variables using:
s=
X
g[f ({Xi })]
i
Here g is a function of a scalar and f is a function that takes in the positions of a set of atoms {X} and outputs a
scalar. The sum then runs over the different sets of atoms from which the quantity f can be calculated. This is all
rather abstract so lets make it more concrete by considering an example. Suppose that we want to calculate the
coordination number of atom k . What we need to do is:
Generated by Doxygen
11.21 Lugano tutorial: Analyzing CVs
817
1. We need to calculate the distance between atom k and every atom in the system that is not atom k . This will
be the set of sets of atoms that we have to perform the sum above on. Furthermore, the function f in the
above will be Pythagoras theorem, which is the function we use to calculate the distance between a pair of
atoms.
2. We need to transform the distances calculated by a switching function ( f in the above) that is equal to one if
the distance is less than or equal to the typical length of a chemical bond and zero otherwise.
Lets thus use PLUMED to calculate the coordination number of atom 9. We can do this as follows:
d1: DISTANCES GROUPA=9 GROUPB=1-8,10-256 LESS_THAN={RATIONAL D_0=0.16 R_0=0.01 D_MAX=0.2}
PRINT ARG=d1.* FILE=colvar
Copy this input file to a PLUMED input file. Before using it to analyze the trajectory that you downloaded at the start
of the exercise using the commands described in section Introduction to the PLUMED input file try to guess what
value this coordination number will take. Hint: what element is atom 9?
Now see if you can adjust the above input to calculate the coordination number of atom 5. What is the coordination
number of this atom and why does it take this value?
11.21.4.8
Multicolvar
In the previous section we exploited a feature of PLUMED known as multicolvar when calculating the coordination
number. When using this feature we are not confined to simply calculating coordination numbers. For instance
the input below allows us to calculate a number of distances and to then calculate the mean of the distribution
of distances, the minimum distance in the distribution, the maximum distance in the distribution and the second
moment of the distribution (the variance).
ca: GROUP ATOMS=9,16,31,55,69,90,102,114,124,138,160,174,194,208,224,238
dd: DISTANCES GROUP=ca MEAN MIN={BETA=50} MAX={BETA=0.02} MOMENTS=2
PRINT ARG=dd.mean,dd.min,dd.max,dd.moment-2 STRIDE=1 FILE=COLVAR
ENDPLUMED
Try to copy this input now and to use it to analyze the trajectory you downloaded at the start of the exercise using
the commands described in section Introduction to the PLUMED input file.
Multicolvar is not just for DISTANCES though. The infrastructure of multicolvar has been used to develop many
PLUMED2 collective variables. One interesting example is the set of Secondary Structure CVs (ANTIBETARMSD,
PARABETARMSD and ALPHARMSD). You can use the input below to calculate the degree of anti-beta secondary
structure in each of the trajectory frames by copying this input to a PLUMED input file and by exploiting the commands to run driver that were described in section Introduction to the PLUMED input file.
MOLINFO STRUCTURE=template.pdb
abeta: ANTIBETARMSD RESIDUES=all TYPE=DRMSD LESS_THAN={RATIONAL R_0=0.08 NN=8 MM=12} STRANDS_CUTOFF=1
PRINT ARG=abeta.lessthan STRIDE=1 FILE=COLVAR
ENDPLUMED
We can do a large number of other things with multicolvar. If you are interested this topic is described in more detail
in the tutorial: Belfast tutorial: Steinhardt Parameters.
Generated by Doxygen
818
11.21.4.9
Tutorials
Understanding the need for ensemble averages
In the previous sections we have learned how we can use PLUMED to calculate collective variables from simulation
trajectories and have seen how, by plotting how these collective variables change as a function of time, we can get
a handle on what happens during the trajectory. Generally this level of analysis is not sufficient for us to publish a
paper about the simulations we have run, however. In this section we are going to run some molecular dynamics
simulations in order to understand why.
You are going to need to do the following set of things in order to do this exercise:
1. Take the two files you downloaded at the start of this exercise that are called called in and input.xyz and place
them in a directory.
2. In the same directory write an input file for PLUMED called plumed.dat that calculates and prints the distance
between atoms 2 and 3 to a file called colvar.
3. Run simplemd by issuing the command:
plumed simplemd < in
1. Open the file called input.xyz and modify the z-coordinate of the 1st atom. It should currently be equal to
zero. Set it equal to 0.1.
2. Run simplemd again using the command above.
3. Plot the colvar files output during the two calculations using:
gnuplot
p ’colvar’ w l, ’bck.0.colvar’ w l
If you have done everything correctly you should see that the values of the distance in the early parts of the
simulation are similar but that the values of the distance in the two simulations are very different by the end of the
simulations.
Allow me to explain what we have just done. simplemd is a tool for running molecular dynamics using the
Lennard-Jones potential. We have thus just run two very similar molecular dynamics calculations. The only
difference between these two calculations was in the z-coordinate of the first atom in the input structure. The initial
velocities of all the atoms were the same and the initial positions of all other atoms were identical. In spite of these
similarities, however, the trajectories that we obtain in the two calculations are very different. This is important as it
tells us that the time series of CV values that we get from a single MD simulation is (in and of itself) not particularly
valuable as we would have got a completely different time series of values if we had run the calculation with only a
slightly different input structure. We should, therefore, think of the trajectory output from a molecular dynamics
simulations as a time series of random variables and analyze it accordingly.
The justification for thinking of a trajectory as a time series of random variables is based on statistical mechanics
which tells us that a system with a constant number of atoms and a constant volume evolving at a fixed temperature
has a probability:
P (q) ∝ e
U (q)
BT
−k
of being in a microstate q with internal energy U (q) as discussed and explained in the videos that can be found on
the following pages:
Generated by Doxygen
11.21 Lugano tutorial: Analyzing CVs
819
• http://gtribello.github.io/mathNET/PRINCIPLE_OF_EQUAL_APRIORI_PROBABIL←-
ITIES.html
• http://gtribello.github.io/mathNET/GENERALIZED_PARTITION_FUNCTION.html
• http://gtribello.github.io/mathNET/CANONICAL_ENSEMBLE.html
Now, and as already explained above, given that each microstate is sampled with this particular probability it makes
sense to think of the microstates, and by extension the collective variables values that we calculate from these
microstates, as random variables. We can thus define the ensemble average for a particular collective variable, A,
using:
Z
hAi =
A(q)P (q)dq
where the integral here runs over all possible microstates, A(q) is the function that allows us to calculate the value
of the CV from the positions of the atoms in microstate q and where P (q) is the "probability" (as it appears in an
integral it is, strictly speaking, a probability density) of being in microstate q which was introduced above. For more
information on this business of random variables and ensemble averages (or expectations) check out the videos
that can be found on the following pages:
• http://gtribello.github.io/mathNET/RANDOM_VARIABLES.html
• http://gtribello.github.io/mathNET/EXPECTATION.html
Instead of using the formula for the ensemble average given above we can estimate an ensemble averages by
taking a time series of random variables (like our trajectory) adding all the values of the random variable together (in
our case the CV values in each of the trajectory frames) and dividing by the number of random variables that were
added together. This works because of results known as the law of large numbers and the central limit theorem,
which you can find videos on here:
• http://gtribello.github.io/mathNET/LAW_OF_LARGE_NUMBERS.html
• http://gtribello.github.io/mathNET/CENTRAL_LIMIT_THEOREM.html
Alternatively, we can justify this way of analyzing our trajectory by thinking of the set of sampled frames as random
variables generated from Markov chain.
These mathematical objects are discussed here:
• http://gtribello.github.io/mathNET/MARKOV_PROPERTY.html
• http://gtribello.github.io/mathNET/CHAPMAN_KOLMOGOROV_RELATION.html
• http://gtribello.github.io/mathNET/TRANSIENT_RECURRENT_STATES.html
• http://gtribello.github.io/mathNET/STATIONARY_DIST_MARKOV.html
Regardless, however, and as we will see in the following section we can estimate ensemble averages of collective
variables using:
hAi ≈
1X
A[q(t)]
T t
where the sum runs over the set of T microstates, q(t), in our trajectory and where A[q(t)] is the function that is
used to calculate the value of the collective variable from the positions of the atoms in the microstate. When we
do so we find that the values of the ensemble averages from different trajectories are reasonably consistent and
certainly much more consistent than the set of instantaneous CV values.
Generated by Doxygen
820
11.21.4.10
Tutorials
Calculating ensemble averages using PLUMED
Repeat the steps from the previous section that were used to run the two MD calculations with slightly different input
configurations. This time, however, your PLUMED input should look like this:
d1: DISTANCE ATOMS=2,3
d1a: AVERAGE ARG=d1 STRIDE=10
PRINT ARG=d1,d1a FILE=colvar STRIDE=10
If you now plot the values of the CV output from these two calculations together with the estimates of the ensemble
averages using something like the commands below:
gnuplot
p ’colvar’ u 1:2 w l, ’’ u 1:3 w l, ’bck.0.colvar’ u 1:2 w l, ’’ u 1:3 w l
You should see that, although the instantaneous values of the CVs differ greatly in the two simulations, the average
values of the CVs are relatively similar for both simulations.
Lets discuss the AVERAGE command that we have added here and what this does. In essence it accumulates
the sum of all the distances calculated by the DISTANCE command labelled d1. When it comes time to output
this accumulated average (every 10 trajectory steps) this accumulated sum is divided by the number of trajectory
frames that have been summed in calculated the current sum. In other words, the average allows us to compute
the following quantity:
a=
N
1 X
d(ti )
N i=1
where d(ti ) is the value of the distance at time ti . Now you may reasonably ask: what the keyword STRIDE=10 is
doing in this command?
Well this is telling PLUMED to only add distances into the accumulated average every 10 steps. In other words,
when calculating the average we are disregarding the value of the distance in frames 1,2,3,4,5,6,7,8 and 9. Why
are we disregarding this information though? Well because there are correlations between the values the CV takes
in two adjacent trajectory frames. Ideally, we want the values of the distance we are averaging to be independent
and identical random variables.
Before we move on to calculating histograms and free energy surfaces I have a little challenge for you. If you
are able to answer the following question then you really understand what the AVERAGE command is doing. Try
running the calculation above using the following input:
d1: DISTANCE ATOMS=2,3
d1a: AVERAGE ARG=d1 STRIDE=10 CLEAR=10
PRINT ARG=d1,d1a FILE=colvar STRIDE=10
Based on what you see when you plot the colvar file and the information on the page about the AVERAGE command
what is the CLEAR=10 keyword telling PLUMED to do?
Generated by Doxygen
11.21 Lugano tutorial: Analyzing CVs
11.21.4.11
821
Calculating histograms
Most of the time, we are not really interested in calculating ensemble averages for particular collective variables.
What we would really like is the probability that the collective variable takes a particular value or set of values. In
other words, and as discussed in the following video, we would like the probability as a function of collective variable
value:
• https://www.youtube.com/watch?v=-1NLaqOJKS0
We can calculate approximate histograms like these using PLUMED. Furthermore, and as discussed in the video
below, when we do this what we are really doing is we are calculating multiple ensemble averages at once:
• http://gtribello.github.io/mathNET/histogram-video.html
To calculate these ensemble averages we must make use of the HISTOGRAM command. An input file for a calculation of this sort is provided below. Use this input now and the input files for simple MD from the previous two
sections to calculate the histogram of DISTANCE values that are explored in these trajectories.
d1: DISTANCE ATOMS=2,3
histogram: HISTOGRAM ARG=d1 BANDWIDTH=0.05 GRID_MIN=0 GRID_MAX=4.0 GRID_BIN=200 STRIDE=10
DUMPGRID GRID=histogram FILE=histo STRIDE=25000
You can plot the histogram output from this simulation using:
gnuplot
p ’histo’ w l
You should see that there is a large peak in the histogram at around 2.0 indicating that this is the value of the
distance that the atoms were most likely to have during the course of the simulation. N.B. The histogram is unlikely
to be converged with a trajectory this short.
Lets now look at the syntax of the HISTOGRAM command. The first thing to note is the similarities between what
is done with this command and what is done with the AVERAGE command. Once again we have a STRIDE
keyword for HISTOGRAM (and a CLEAR keyword for that matter) that tells us how often data should be added
to to the accumulated averages. Furthermore, in both these commands we have an additional instruction with its
own STRIDE keyword (PRINT for AVERAGE and DUMPGRID for HISTOGRAM) that tells us how frequently the
accumulated averages should be output to human readable files.
A substantial difference between these two input files is the object the label histogram refers to. In all previous examples the label of an action has referred to a scalar quantity that was calculated by that action. In the example above,
however, the label histogram refers to the function accumulated on a grid that is evaluated by the HISTOGRAM
command. This is why we cannot print this quantity using PRINT - it is not a simple scalar valued function anymore.
As you become more familiar with PLUMED you will find that these labels can refer to a range of different types of
mathematical object.
Lets now see if we can bring together everything we have learned in this tutorial in order to analyze the protein
trajectory that was downloaded at the start of the exercise.
Generated by Doxygen
822
11.21.4.12
Tutorials
A histogram for the protein trajectory
We are going to calculate the HISTOGRAM from our protein trajectory as a function of two different collective
variables: ANTIBETARMSD and the average distance between the ca atoms of our protein backbone. The input
that allows us to calculate perform this analysis is shown below:
# Read in protein structure template
MOLINFO STRUCTURE=template.pdb
# Calculate collective variables
abeta: ANTIBETARMSD RESIDUES=all TYPE=DRMSD LESS_THAN={RATIONAL R_0=0.08 NN=8 MM=12} STRANDS_CUTOFF=1
ca: GROUP ATOMS=9,16,31,55,69,90,102,114,124,138,160,174,194,208,224,238
DISTANCES GROUP=ca MEAN MIN={BETA=50} MAX={BETA=0.02} MOMENTS=2 LABEL=dd
# Print instaneous values of collective variables
PRINT ARG=abeta.lessthan,dd.mean,dd.min,dd.max,dd.moment-2 STRIDE=1 FILE=COLVAR
# Accumulate histogram of collective variables
hh: HISTOGRAM ARG=abeta.lessthan,dd.mean KERNEL=DISCRETE GRID_MIN=0,0.8 GRID_MAX=4,1.2 GRID_BIN=40,40
# Output histogram - N.B. when we are running with driver we can not provide a STRIDE.
# The histogram will then only be output once all the trajectory frames have been read in and analyzed
DUMPGRID GRID=hh FILE=histo
Try running the input above on the trajectory that you downloaded at the start of this exercise by using the commands
detailed in section Introduction to the PLUMED input file. You can plot the two dimensional histogram output using
the following commands:
gnuplot
set pm3d map
sp ’histo’ w pm3d
If you do so though, you will probably find that the structure in the histogram, H(s), is a bit difficult to visualize
because the probability changes from point to point by multiple orders of magnitude. This is why we often convert
the histogram, H(s), to a free energy surface, F (s), using:
F (s) = −kB T ln H(s)
If you want to use PLUMED to output the free energy rather than the histogram you need to use the
CONVERT_TO_FES command as shown below:
# Read in protein structure template
MOLINFO STRUCTURE=template.pdb
# Calculate collective variables
abeta: ANTIBETARMSD RESIDUES=all TYPE=DRMSD LESS_THAN={RATIONAL R_0=0.08 NN=8 MM=12} STRANDS_CUTOFF=1
ca: GROUP ATOMS=9,16,31,55,69,90,102,114,124,138,160,174,194,208,224,238
DISTANCES GROUP=ca MEAN MIN={BETA=50} MAX={BETA=0.02} MOMENTS=2 LABEL=dd
# Print instaneous values of collective variables
PRINT ARG=abeta.lessthan,dd.mean,dd.min,dd.max,dd.moment-2 STRIDE=1 FILE=COLVAR
# Accumulate histogram of collective variables
hh: HISTOGRAM ARG=abeta.lessthan,dd.mean KERNEL=DISCRETE GRID_MIN=0,0.8 GRID_MAX=4,1.2 GRID_BIN=40,40
fes: CONVERT_TO_FES GRID=hh TEMP=300
# Output free energy - N.B. when we are running with driver we can not provide a STRIDE.
# The histogram will then only be output once all the trajectory frames have been read in and analyzed
DUMPGRID GRID=fes FILE=fes.dat
Notice though that even when we do this complicated looking calculation we are still, underneath it all, calculating
functions of a large number of ensemble averages.
Generated by Doxygen
11.22 Lugano tutorial: Path CVs
11.21.5
823
Conclusions and further work
If you have worked through all of this tutorial make sure that you have understood it by ensuring that you understand
what the list of learning outcomes in section Learning Outcomes means and that you can use PLUMED to perform
all these tasks. In terms of further work you should investigate issues related to the convergence of estimates of
ensemble averages such as block averaging. You might like to investigate how long your simulations have to be in
order to obtain reliable estimates of the ensemble average for a collective variable and reliable estimates for the free
energy as a function of a collective variable. Alternatively, you might like to explore other collective variables that
could be used to analyze the protein trajectory that you have worked on in this tutorial.
11.22
Lugano tutorial: Path CVs
11.22.1
Aims
Consider the two overlain protein structures that are shown in the figure below.
Can you see the difference between these two structures? Can you think of a collective variable that could be used
to study the substantial change in structure?
Your answers to the questions posed above are hopefully: yes I can see the difference between the two structures
- the upper loop is radically different in the two cases - and no I have absolutely no idea as to how to create a
collective variable that might be used to study the change in structure.
These answers are interesting as they cut to the very heart of what is interesting about biomolecular systems. In
fact this difficulty is one of the reasons why such systems are so widely studied. If you think for a moment about
solid state systems any transition usually involves a substantial change in symmetry.
Low energy configurations are usually high symmetry while higher energy configurations have a low symmetry.
This makes it easy to design collective variables to study solid state transitions - you simply measure the degree
of symmetry in the system (see Belfast tutorial: Steinhardt Parameters). In biomolecular systems by contrast the
symmetry does not change substantially during a folding transition. The unfolded state has a low symmetry but the
folded state also has a low symmetry, which is part of the reason that it is so difficult to find the folded state from the
amino acid sequence alone.
With all this in mind the purpose of this tutorial is to learn about how we can design collective variables that can
be used to study transitions between different states of these low-symmetry systems. In particular, we are going
to learn how we can design collective variables that describe how far we have progressed along some pathway
between two configurations with relatively low symmetry. We will in most of this tutorial study how these coordinates
work in a two-dimensional space as this will allow us to visualize what we are doing. Hopefully, however, you will be
able to use what you learn from this tutorial to generalize these ideas so that you can use PATH and PCAVARS in
higher-dimensional spaces.
11.22.2
Learning Outcomes
Once this tutorial is completed students will:
• be able to explain what is computed by a PCAVARS coordinate and write down expressions for these quantities.
• be able to write a PLUMED input file that calculates and prints a PCAVARS coordinate.
• be able to write down an expression for the quantity contained in the s and z components of a PATH collective
variable.
• be able to write PLUMED input files that calculate PATH collective variables for a range of different metrics.
• be able to measure the quality of a transition state by calculating the isocommittor.
Generated by Doxygen
824
Tutorials
11.22.3
Resources
The tarball for this project contains the following files:
• transformation.pdb : a trajectory that shows the transition between the C7 ax and C7 eq conformers of alanine
dipeptide.
• pca-reference.pdb : a file that gives the start and end points of the vector that connects the C7 ax and C7 eq
conformers. This file contains the positions of the atoms in these two structures.
• PCA-isocommittor : a directory containing the files required to run isocommittor simulations that monitor the
values of φ, ψ and the PCA coordinate.
• PATH-isocommittor : a directory containing the files required to run isocommittor simulations that monitor the
values of the PATH collective variable S(X).
• 2CV-isocommittor : a directory containing the files required to run isocommittor simulations that monitor the
values of the PATH collective variables S(X) and Z(X)
11.22.4
Instructions
In this tutorial we are going to be considering a conformational transition of alanine dipeptide. In particular we are
going to be considering the transition between the two conformers of this molecule shown below:
Alanine dipeptide is a rather well-studied biomolecule (in fact it is an over studied molecule!). It is well known that
you can understand the inter-conversion of the two conformers shown above by looking at the free energy surface
as a function of the φ and ψ Ramachandran angles as shown below:
In this tutorial we are not going to use these coordinates to study alanine dipeptide. Instead we are going to see if
we can find a single collective variable that can distinguish between these two states.
11.22.4.1
PCA coordinates
Consider the free energy surface shown in figure lugano-2-rama-fig. It is clear that either the φ ( x-axis) or the
ψ ( y -axis) angle of the molecule can be used to distinguish between the two configurations shown in figure
lugano-2-transition-fig. Having said that, however, given the shape of landscape and the associated thermal fluctuations we would expect to see in the values of these angles during a typical simulation, it seems likely that φ will do
a better job at distinguishing between the two configurations. ψ would most likely be a bad coordinate as when the
molecule is in the C7 eq configuration the ψ angle can fluctuate to any value with only a very small energetic cost.
If we only had information on how the ψ angle changed during a simulation we would thus struggle to distinguish a
transition to the C7 ax configuration from a thermal fluctuations. It has been shown that metadynamics simulations
that use just the φ angle as a collective variable can effectively drive the system from the C7 ax configuration to
the C7 eq configuration. We will not repeat these calculations here but will instead use driver to determine how the
values of φ and ψ change as we move between along the transition path that connects the C7 ax configuration to
the C7 eq state.
t1: TORSION ATOMS=2,4,6,9
t2: TORSION ATOMS=4,6,9,11
PRINT ARG=t1,t2 FILE=colvar
Lets run this now on trajectory that describes the transition from the C7 ax configuration to the C7 eq configuration.
To run this calculation copy the input file above into a file called plumed.dat and run the command below:
plumed driver --mf_pdb transformation.pdb
Generated by Doxygen
11.22 Lugano tutorial: Path CVs
825
Try plotting each of the two torsional angles in this file against time in order to get an idea of how good a job each one
of these coordinates at distinguishing between the various configurations along the pathway connecting the C7 ax
and C7 eq configurations. What you will see is that in both cases the CV does not increase/decrease monotonically
as the transition progresses.
We can perhaps come up with a better coordinate that incorporates changes in both φ and ψ by using the coordinate
illustrated in the figure below.
We can even use PLUMED to calculate this coordinate by using the input shown below:
t1: TORSION ATOMS=2,4,6,9
t2: TORSION ATOMS=4,6,9,11
tc: COMBINE ARG=t1,t2 COEFFICIENTS=2.621915,-2.408714 PERIODIC=NO
PRINT ARG=t1,t2,tc FILE=colvar
Try calculating the values of the above collective variables for each of the configurations in the transformation.pdb
file by using the command that was given earlier.
Notice that what we are using here are some well known results on the dot product of two vectors here. Essentially
if the values of the Ramachandran angles in the C7 eq configuration are (φ1 , ψ1 ) and the Ramachandran angles
in the C7 ax configuration are (φ2 , ψ2 ). If our instantaneous configuration is (φ3 , ψ3 ) we can thus calculate the
following projection on the vector connecting the C7 eq state to the C7 ax state:
s = (φ2 − φ1 ).(φ3 − φ1 ) + (ψ2 − ψ1 ).(ψ3 − ψ1 )
which is just the dot product between the vector connecting the point (φ1 , ψ1 ) to (φ2 , ψ2 ) and the vector connecting
the point (φ1 , ψ1 ) to (φ3 , ψ3 ). If we call these two vectors v1 and v2 we can write this dot product as:
v1 · v2 = |v1 ||v2 |cos(α)
where |v1 | and |v2 | are the magnitudes of our two vectors and where α is the angle between the two of them.
Elementary trigonometry thus tells us that if v1 is a unit vector (i.e. if it has magnitude 1) the dot product is thus
equal to the projection of the vector v2 on v2 as shown in figure pca-figure.
This is an useful idea. In fact it is the basis of the PCAVARS collective variable that is implemented in PLUMED so
we can (almost) calculate the projection on this vector by using the input shown below:
t1: TORSION ATOMS=2,4,6,9
t2: TORSION ATOMS=4,6,9,11
p: PCAVARS REFERENCE=angle-pca-reference.pdb TYPE=EUCLIDEAN
PRINT ARG=t1,t2,p.* FILE=colvar
We cannot, however, do this in practice (we also shouldn't really use the previous input either) as the TORSION
angles that we use to define our vectors here are periodic. In this next section we will thus look at how we can avoid
this problem of periodicity by working in a higher dimensional space.
Generated by Doxygen
826
11.22.4.2
Tutorials
PCA with the RMSD metric
In the previous section I showed how we can use the projection of a displacement on a vector as a collective variable.
I demonstrated this in a two dimensional space as this makes it easy to visualize the vectors involved. We are not
forced to work with two dimensional vectors, however. We can instead find the vector that connects the C7 eq and
C7 ax states in some higher dimensional space and project our current coordinate on that particular vector. In fact
we can even define this vector in the space of the coordinates of the atoms. In other words, if the 3 N coordinate
of atomic positions is x(1) for the C7 eq configuration and x(2) for the C7 ax configuration and if the instantaneous
configuration of the atoms is x(3) we can use the following as a CV:
s=
3N
X
(2)
(xi
(1)
(3)
− xi )(xi
(1)
− xi )
i=1
where the sum here runs over the 3N -dimensional vector that defines the positions of the N atoms in the system.
This is what (in a manner of speaking - I will return to this point momentarily) is calculated by this PLUMED input:
t1: TORSION ATOMS=2,4,6,9
t2: TORSION ATOMS=4,6,9,11
p: PCAVARS REFERENCE=pca-reference.pdb TYPE=OPTIMAL
PRINT ARG=t1,t2,p.* FILE=colvar
Use this input to analyze the set of configurations that are in the transformation.pdb file.
Let's now look further at the caveat that I alluded to before we ran the calculations. I stated that we are only
calculating:
s=
3N
X
(2)
(xi
(1)
(3)
− xi )(xi
(1)
− xi )
i=1
in a manner of speaking. The point is that we would not want to calculate exactly this quantity because the vectors
of displacements that are calculated in this way includes both rotational and translational motion. This is a problem
as the majority of the change in moving from the C7 ax configuration shown in figure lugano-2-transition-fig to the
C7 eq configuration shown in figure lugano-2-transition-fig comes from the translation of all the atoms. To put this
another way if I had, in figure lugano-2-transition-fig, shown two images of the C7 ax configuration side by side
the displacement in the positions of the atoms in those two structures would be similar to the displacement of the
atoms in lugano-2-transition-fig as as the majority of the displacement in the vector of atomic positions comes about
because I have translated all the atoms in the molecule rightwards by a fixed amount. I can, however, remove
these translational displacements from consideration when calculating these vectors. In addition, I can also remove
any displacements due rotation in the frame of reference of the molecule. If you are interested in how this is done
in practice you can read about it on the manual page about the RMSD collective variable. For what concerns us
here, however, all we need to know is that when we use the OPTIMAL metric we are calculating a vector which
tells us how far the atoms have been displaced in moving from structure A to structure B in a way that excludes
any displacements due to translation of the center of mass of the molecule or any displacements that occur due to
rotation of the Cartesian frame.
11.22.4.3
The isocommittor surface
In the previous sections I have been rather loose when talking about better and worse collective variables in that I
have not been clear in my distinction between what makes a collective variable good and what makes a collective
variable bad. In this section I thus want to discuss one method that we can use to judge the quality of a collective
variable. This method involves calculating the so called isocommittor. The essential notion behind this technique
is that there will be a saddle point between the two states of interest (the C7 ax and C7 eq configurations in our
alanine dipeptide example). If the free energy is plotted as a function of a good collective variable the location of
this dividing surface - the saddle point - will appear as a maximum.
Lets suppose that we now start a simulation with the system balanced precariously on this maximum. The system
will, very-rapidly, fall off the maximum and move towards either the left or the right basin. Furthermore, if this maximum provides a good representation of the location of the transition state ensemble - in other words if the position
Generated by Doxygen
11.22 Lugano tutorial: Path CVs
827
of maximum in the low-dimensional free energy surface tells us something about the structure in the transition state
ensemble - then 50% of trajectories started from this point will fall to the left and 50% will fall to the right. If by contrast the maximum in the free energy surface does not represent the location of the transition state well then there
will be an imbalance between the number of trajectories that move rightwards and the number that move leftwards.
We can think of this business of the isocommittor one further way, however. If in the vicinity of the transition state
between the two basins the collective variable is perpendicular to the surface separating these two states half of the
trajectories that start from this configuration will move to the left in CV space while the other half will move to the
right. If the dividing surface and the CV are not perpendicular in the vicinity of the transition state, however, there
will be an imbalance between the number of trajectories that move rightwards and the number of trajectories that
move leftwards. We can thus determine the goodness of a collective variable by shooting trajectories from what we
believe is the transition state and examining the number of trajectories that move into the left and right basins.
Lets make all this a bit more concrete by looking at how we might calculate the isocommittor by using some of the
collective variables we have introduced in this exercise. You will need to go into the directory in the tar ball that you
downloaded that is called PCA-isocommittor. In this directory you will find a number of files that will serve as input
to gromacs 5 and PLUMED. You thus need to ensure that you have an installed version of gromacs 5 patched with
PLUMED on your computer in order to perform this exercise. In addition to these input files you will find a bash script
called script.sh, which we are going to use in order to set of a large number of molecular dynamics simulations. If
you open script.sh you will find the following lines near the top:
GROMACS_BIN=/Users/gareth/MD_code/gromacs-5.1.1/build/bin
GROMACS=$GROMACS_BIN/gmx
source $GROMACS_BIN/GMXRC.bash
These will need to be adjusted so that the GROMACS_BIN variable points at the bin directory of the gromacs build
on your computer. Once you have made this modification though you can run the calculation by issuing the following
command in the PCA-isocommittor directory:
./script.sh
This command submits 50 molecular dynamics simulations that all start from a configuration that lies between the
C7 eq and C7 ax configurations of alanine dipeptide. In addition, this command also generates some scripts that
allow us to visualize how the φ, ψ and PCA coordinates that we introduced in the previous sections change during
each of these 50 simulations. If you load gnuplot and issue the command:
load "script_psi.gplt"
you see how ψ changes during the course of the 50 simulations. Similarly the gnuplot command:
load "script_phi.gplt"
will show how how φ changes during the course of the 50 simulations and:
load "script_pca.gplt"
Generated by Doxygen
828
Tutorials
gives you the information on the PCA coordinates. If you look at the ψ and PCA data first you can see clearly that
it is very difficult to distinguish the configurations that moved to the C7 eq basin from the trajectories that moved to
the C7 ax basin. By contrast if you look at the data on the φ angles you can indeed use these plots to distinguish
the trajectories that moved to C7 eq from the trajectories that moved to C7 ax. It is abundantly clear, however, that
the number of trajectories that moved to C7 eq is not equal to the number of trajectories that moved to C7 ax. This
CV, therefore, is not capturing the transition state ensemble.
One thing you will have seen from these examples is that the PCAVARS coordinate that were introduced in the
previous sections provides an extremely poor model for the transition state ensemble. The value of the isocommittor
at the maximum for both of these variables is not at all close to 50%. In fact the CV is not even particularly good at
capturing the difference between these two states. If you look at the free energy surface shown below it is perhaps
clear why.
You can see the location of the saddle point between these two states in this surface and it is very clear that the
vector connecting the C7 eq state to the C7 ax state does not pass through this point. In fact it would be extremely
fortuitous if a vector connecting an initial state and a final state also passed through the intermediate transition state
between them. We can, after all, define the equation of straight line (a vector) if we are given only two points on
it. In the next section we are thus going to see how we can resolve this problem by introducing a non-linear (or
curvilinear) coordinate.
11.22.4.4
Path collective variables
Consider the black path that connects the C7 ax and C7 eq states in the free energy shown below:
This black pathways appears to be the "perfect" coordinate for modelling this conformational transition as it passes
along the lowest energy pathway that connects the two states and because it thus passes over the lowest saddle
point that lies between them. We can calculate such a coordinate with PLUMED by using the input file below (I will
return to the mathematical details of how this works momentarily)
path: PATH REFERENCE=path-reference.pdb TYPE=OPTIMAL LAMBDA=15100.
PRINT ARG=* STRIDE=2 FILE=colvar FMT=%12.8f
Lets thus use this input and run an isocommittor analysis using the location of the maximum in this coordinate as
the start point for all our trajectories. Everything you need to do this analysis is in the PATH-isocommittor directory.
Once again you will find that there is a script.sh bash script inside this directory, which, as in the previous section,
you can use to run a large number of molecular dynamics simulation. Furthermore, similarly to the last section you
will need to begin this exercise by modifying the location of path to gromacs within this script. Once you have made
this modification submit your molecular dynamics jobs by issuing the command:
./script.sh
You can then plot the data output using gnuplot and the command:
load "script_path.gplt"
Unlike what we saw for the PCAVARS variables in the previous section we find that it is easy to use these PATH
variables to distinguish those configurations that moved to C7 ax from those that moved to C7 eq . Having said that,
however, we still have a large imbalance between the number of trajectories that move rightwards and the number
that move leftwards. We are thus still a long way from unambiguously identifying the location of the transition state
ensemble for this system.
Generated by Doxygen
11.22 Lugano tutorial: Path CVs
11.22.4.5
829
The mathematics of path collective variables
Let's now take a moment to discuss the mathematics of these coordinates, which is not so complicated if we think
about what they do through an analogy. Suppose that you were giving your friend instructions as to how to get to
your house and lets suppose these instructions read something like this:
1. Take the M1 motorway and get off at junction 5
2. At the roundabout you need to take the third exit towards Crumlin
3. Follow the road as far as the farmers arms then take the next left
4. The house is on the corner by the garage.
If you think about these instructions in the abstract what you have is a set of way markers (the item I have
put in bold) in a particular order. The list of way markers is important as is the order they appear in in the
instructions so we incorporate both these items in the PATH coordinates that we have just used to study the
transition between the transition between C7 eq and C7 ax. In these coordinates the way markers are a set of
interesting points in a high dimensional space. In other words, these are like the configurations of C7 eq and
C7 ax that we used in the previous sections when talking about PCAVARS. Each of these configurations lies
along the path connecting C7 eq and C7 ax and, as in the directions example above, one must pass them in a
particular order in order to pass between these two conformations. The final CV that we have used above is
thus:
PN
S(X) = Pi=1
N
i exp−λ|X−Xi |
i=1
exp−λ|X−Xi |
In this expression |X − Xi | is the distance between the instantaneous coordinate of the system, X , in the highdimensional space and Xi is the coordinate of the ith way mark in the path. The largest exponential in the sum that
appears in the numerator and the denominator will thus be the one that corresponds to the point that is closest to
where the system currently lies. In other words, S(X), measures the position on a (curvilinear) path that connects
two states of interest as shown in red in the figure below:
11.22.4.6
The Z(X) collective variable
You may reasonably ask what the purpose these PATH collective variables variables serve given that in this case
they seem to do no better than φ when it comes to the tests we have performed on calculating the isocommittor. To
answer this question we are going to run one final set of isocommittor simulations. The input for these calculations
are in the directory called 2CV-isocommittor. Once again you will find that there is a script.sh bash script inside this
directory, which, as in the previous section, you can use to run a large number of molecular dynamics simulation.
Furthermore, similarly to the last section you will need to begin this exercise by modifying the location of path to
gromacs within this script. Once you have made this modification submit your molecular dynamics jobs by issuing
the command:
./script.sh
You can then plot the data output using gnuplot and the commands:
load "script_pca.gplt"
and
Generated by Doxygen
830
Tutorials
load "script_path.gplt"
What is plotted by these commands is slightly different from what was plotted in the previous exercises where we
calculated the isocommittor.
Instead of plotting the value of the CV against simulation time the above commands plot the values that 2CVs take
during the simulation. The script called script_path.gplt plots the value of the S(X) collective variable on the x-axis
and the value of the following quantity on the y-axis:
N
X
1
Z(X) = − log(
exp−λ|X−Xi | )
λ
i=1
What this quantity measures is shown in green in the figure lugano-2-ab-sz-fig. Essentially it measures the distance
between the instantaneous configuration the system finds itself in and the path that is marked out using the way
markers. If you plot the data using script_path.gplt what you thus see is that the system never moves very far from
the path that is defined using the PATH command. In short the system follows this path from the transition state
back to either the C7 eq or C7 ax configuration.
We can calculate a quantity similar to Z(X) for the PCAVARS collective variables. Furthermore, when we plot
the data we have generated using this exercise using script_pca.gplt the value this quantity takes is shown plotted
against the instantaneous value of the PCAVARS collective variable. If you compare this graph with what was
obtained when you plotted the output from PATH above you see that the system has moved very far from the
PCAVARS coordinate.
This exercise illustrates the strength of these PATH collective variables. We can use a PATH to monitor how a large
number of coordinates change during a chemical transition. Furthermore, we can use Z(X) to measure how much
real trajectories deviate from our PATH and thus have a quantitative measure of how well our PATH represents the
true transition mechanism. Compare this with using a single CV such as φ. When use use a single CV we map the
high-dimensional data from the trajectory into a lower dimensional space. We thus lose some information on what
occurs during the transition.
To be clear we also loose information on the what occurs during the transition when we use PATH as any mapping
into a lower dimensional space deletes information. In the PATH case, however, we can use the value of Z(X) to
measure how much data has been lost in mapping the trajectory onto S(X).
These two coordinates, S(X) and Z(X), are very flexible. They are thus been used widely in the literature on
modelling conformational changes of biomolecules. A part of this flexibility comes because one can use any set of
way markers to define the PATH. Another flexibility comes, however, when you recognize that you can also change
the way in which the distance, |X − Xi |, is calculated in the two formulas above. For example this distance can
be calculated using the RMSD distance or it can be calculated by measuring the sum of the squares of a set of
displacements in collective variable values (see TARGET). Changing the manner in which the distance between
path way points is calculated thus provides a way to control the level of detail that is incorporated in the description
of the reaction PATH.
11.22.4.7
Optimizing path collective variables
Hopefully the previous sections have allowed you to understand how PATH collective variables work and the sorts
of problems they might be used to solve. If you have one of these problems to solve the next reasonable question to
ask is: how to collect the set of reference frames that serve as the way markers on your PATH. Unfortunately, there
is no single answer to this question. Different researchers have used different methods including using packages
that morph one protein structure into another, using information from prior molecular dynamics or enhanced sampling calculations and even using PATH collective variables that change adaptively as the simulation progresses.
Ultimately, you will need to find the best method for solving your particular problem. Having said that, however, there
is some general guidance on setting up PATH collective variable and it is this that we will focus on in this section.
The first thing that you will need to double check is the spacing between the frames in your PATH. Lets suppose
that your PATH has N of these way markers upon it you will need to calculate is the N × N matrix of distances
Generated by Doxygen
11.23 ESDW Workshop Lyon 2019: A very simple introduction to PLUMED
831
between way markers. That is to say you will have to calculate the distance |Xj − Xi | between each pair of frames.
The values of the distance in this matrix for a good PATH are shown in the figure below:
For contrast the values of the distances in this matrix for a bad PATH are shown in the figure below:
If the distance matrix looks like the second of the two figures shown above this is indicates that the frames in
the PATH that have been chosen are not particularly effective. Lets suppose that we have a PATH with four way
markers upon it. In order for the S(x) CV that was defined earlier to work well frame number 3 must be further
from frame number 1 than frame number 2. Similarly frame number 4 must be still further from frame number 1
than frame number 3. This is what the gull wing shape in lugano-2-good-matrix-fig is telling us. The order of the
frames in the rows and columns of the matrix is the same as the order that they are run through in the sums in
the equation for S(X). The shape of the surface in this figure shows that the distance between frames i and j
increases monotonically as the magnitude of the difference between i and j is increased, which is what is required.
A second important requirement of a good PATH is shown in the figure below:
A good PATH has an approximately equal spacing between the neighboring frames along it. In other words, the
distance between frame 1 and frame 2 is approximately equal to the distance between frame 2 and frame 3 as
shown above. When this condition is satisfied a good criterion for selecting a suitable λ parameter to use is:
2.3(N − 1)
λ = PN −1
i=1 |Xi − Xi+1 |
11.22.5
Conclusions and further work
If you have worked through all of this tutorial make sure that you have understood it by ensuring that you understand
what the list of learning outcomes in section Learning Outcomes means and that you can use PLUMED to perform
all these tasks. You might then want to read the original paper on the PATH collective variable method as well as a
few other articles in which these coordinates have been used to analyze simulations and to accelerate sampling.
• Davide Branduardi and Francesco Luigi Gervasio and Michele Parrinello From A to B in free
energy space J. Chem. Phys., 126, 054103 (2007)
If you are interested in learning more about isocommittor surfaces and the transition state ensemble you should
read up on the transition path sampling method.
11.23
ESDW Workshop Lyon 2019: A very simple introduction to PLUMED
11.23.1
Aims
The aim of this tutorial is to give you a quick introduction to the PLUMED syntax and to some of the types of
calculations that can be done with PLUMED. It was prepared for a two and a half hour session on PLUMED in the
following CECAM extended software development workshop on topics in classical MD:
https://www.cecam.org/workshop-1802.html
This tutorial is very straightforward and not at all exhaustive. In fact it skims over many of the subtleties associated
with performing these types of calculations using PLUMED. We have thus suggested additional topics that you might
like to look into throughout the tutorial in order to take this further.
If you are interested in using the techniques described in the tutorial in your own work a good starting point might
be to read the chapter we wrote about using metadynamics from within PLUMED:
https://arxiv.org/abs/1812.08213
Generated by Doxygen
832
Tutorials
11.23.2
Objectives
Once this tutorial is completed students will be able to:
• Run simulations using the internal PLUMED MD engine simplemd.
• Use PLUMED to add additional forces in order to prevent clusters from dissociating.
• Use PLUMED to calculate and PRINT the value of a collective variable.
• Use the PLUMED HISTOGRAM and CONVERT_TO_FES actions to calculate an estimate of the free energy
as a function of some collective variables.
• Run metadynamics using the action METAD in order to enhance sampling along collective variables of interest.
11.23.3
Resources
TheTARBALL for this project contains the following files:
• in : The input file for simplemd that contains the parameters for the MD simulation.
• input.xyz : An initial configuration for the cluster that we are studying in this tutorial.
• plumed.dat : An empty input file for PLUMED
This tutorial has been tested on v2.5 but it should also work with other versions of PLUMED.
Also notice that the .solutions direction of the tarball contains correct input files for the exercises. Please only
look at these files once you have tried to solve the problems yourself. Similarly the tutorial below contains questions
for you to answer that are shown in bold. You can reveal the answers to these questions by clicking on links within
the tutorial but you should obviously try to answer things yourself before reading these answers.
11.23.4
Introduction
In this tutorial we are going to study a very simple physical system; namely, seven Lennard Jones atoms in a two
dimensional space. This simple system has been extensively studied as has often been used to benchmark new
simulation techniques. In addition, the potential energy landscape has been fully characterized and it is known that
only the four structurally-distinct minima shown below exist:
In the exercises that follow we are going to learn how to use PLUMED to determine the relative free energies of
these four structures by running molecular dynamics simulations.
Generated by Doxygen
11.23 ESDW Workshop Lyon 2019: A very simple introduction to PLUMED
11.23.5
833
Exercises
Before completing the following exercises you will need to download and install PLUMED. In addition, you will need
to ensure that the PLUMED executable can be found within your path.
You can download PLUMED from:
http://www.plumed.org/get-it or https://github.com/plumed/plumed2
If you are running PLUMED on a Mac you can install the executable directly using macports and the command:
sudo port install plumed
If you download the source code you can find instructions on compilation in the PLUMED page on Installation. If
you run make install PLUMED or install with macports PLUMED will be within your path.
If, however, you do not wish to do a make install you can simple make PLUMED. You can then add the location of
the PLUMED executable to your path by issuing the command:
source sourceme.sh
from within the plumed2 directory.
11.23.5.1
Using PLUMED as an MD code
PLUMED is primarily used as a plugin to other larger molecular dynamics codes. Mainly for software testing and
educational purposes, however, we do have an MD code with a rather limited set of functionalities within PLUMED.
You can run this code by issuing the command:
plumed simplemd < in
where in here is the input file from the tar ball for this tutorial, which is shown below:
nputfile input.xyz
outputfile output.xyz
temperature 0.5
tstep 0.005
friction 0.1
forcecutoff 2.5
listcutoff 3.0
ndim 2
nstep 200000
nconfig 1000 trajectory.xyz
nstat
1000 energies.dat
This input instructs PLUMED to perform 200000 steps of MD at a temperature of kB T = 0.5 starting from the
√
configuration in input.xyz. The timestep in this simulation is 0.005 mσ 2 and the temperature is kept fixed using
√
a Langevin thermostat with a relaxation time of 0.1 mσ 2 . Trajectory frames are output every 1000 MD steps to
a file called trajectory.xyz. Notice also that in order to run the calculation above you need to provide an empty file
called plumed.dat. This file is the input file to the PLUMED plugin itself, which, because this file is empty, is doing
nothing when we run the calculation above.
Run a calculation using simplemd and the input above and visualize the trajectory that is output. Describe
what happens during this calculation and explain why this is happening.
You can visualize what occurs during the trajectory by using a visualization package such as VMD (https←://www.ks.uiuc.edu/Research/vmd/). If you are using VMD you can see the MD trajectory by using the
command:
vmd trajectory.xyz
You should observe that all the atoms fly apart early on in the simulation and that the cluster evaporates. The cluster
evaporates because at a temperature of kB T = 0.5 the gas state has a lower free energy than than the cluster
state.
Change the parameters in the input file for simplemd so as to prevent the cluster from evaporating.
To prevent the cluster from evaporating you need to lower the temperature in the file in. The cluster will not evaporate
if the temperature is set equal to kB T = 0.2.
Generated by Doxygen
834
11.23.5.2
Tutorials
Using PLUMED to specify a force field
If we lower the temperature of the simulation very little will happen. Yes the cluster will no longer evaporate but at the
same time we will not see any transitions between the various basins in this energy landscape. In this section we
are thus going to see how we can use PLUMED to add a bias potential that can prevent the cluster from exploring
gaseous configurations that do not interest us. In other words, we are going to see how we can use PLUMED to
add restraints that will prevent the cluster from evaporating. Before getting on to that, however, we first need to
understand a little about how the PLUMED input file works. As explained in The structure of a PLUMED input file
and Getting Started when you write a PLUMED input file you are writing a script that calculates functions of the
atomic positions.
Read the description of the PLUMED input syntax in the linked pages in the paragraph above and then
attempt the exercise that follows
We are going to prevent the cluster from evaporating by adding a restraint on all the atoms so as to prevent them
from moving more than 2σ from the center of mass of the cluster. As the masses of all the atoms in the cluster are
the same we can compute the position of the center of mass using:
xcom =
N
1 X
xi
N i=1
where xi is the position of the ith atom. The distance between the ith atom and the position of this center of
mass, di , can be computed using Pythagoras' theorem. These distances are then restrained by using the following
potential:
V (di ) = { 1 00 ∗ (di − 2.0)2 if di > 20otherwise
as you can see this potential has no effect on the dynamics when these distances are less than 2 . If any atom is
more than 2 from the center of mass, however, this potential will drive it back towards the center of mass. The
following cell contains a skeleton input file for PLUMED that gets it to calculate and apply this bias potential.
BEGIN_PLUMED_FILE
# this optional command tells VIM that this is a PLUMED file and to color the text accordingly
# vim: ft=plumed
# This tells PLUMED we are using Lennard Jones units
UNITS NATURAL
# Calculate the position of the center of mass.
com: COM __FILL__
We can then refer to this position later in the input using t
# Add the restraint on the distance between com and the first atom
d1: DISTANCE __FILL__
UPPER_WALLS ARG=d1 __FILL__
# Add the restraint on the distance between com and the second atom
d2: DISTANCE __FILL__
UPPER_WALLS __FILL__
# Add the restraint on the distance between com and the third atom
d3: DISTANCE __FILL__
UPPER_WALLS __FILL__
# Add the restraint on the distance between com and the fourth atom
d4: DISTANCE __FILL__
UPPER_WALLS __FILL__
# Add the restraint on the distance between com and the fifth atom
d5: DISTANCE __FILL__
UPPER_WALLS __FILL__
# Add the restraint on the distance between com and the sixth atom
d6: DISTANCE __FILL__
UPPER_WALLS __FILL__
# Add the restraint on the distance between com and the seventh atom
d7: DISTANCE __FILL__
UPPER_WALLS __FILL__
Generated by Doxygen
11.23 ESDW Workshop Lyon 2019: A very simple introduction to PLUMED
835
Copy and paste the content above into the file plumed.dat and then fill in the blanks by looking up the
documentation for these actions online and by reading the description of the calculation that you are to
run above. Once you have got a working plumed.dat file run a calculation using simplemd again at a
temperature of kB T = 0.2 and check to see if the bias potential is indeed preventing the cluster from
evaporating.
11.23.5.2.1
Extensions
Try the following exercises if you have time and if you wish to take this exercise further:
• See if you can rewrite the input above in a more compact way by making use of DISTANCES and UWALLS.
• Checkout the hack-the-tree branch of PLUMED. This version of PLUMED allows you to pass vector quantities
between actions as well as scalars. See if you can rewrite the above input using this version of PLUMED by
making use of the MATHEVAL and BIASVALUE actions.
11.23.5.3
Calculating collective variables
We can easily determine if there are transitions between the four possible minima in the Lennard-Jones-seven
potential energy landscape by monitoring the second and third central moments of the distribution of coordination
numbers. The nth central moment of a set of numbers, {Xi } can be calculated using:
µn =
N
1 X
(Xi − hXi)n
N i=1
where
hXi =
N
1 X
Xi
N i=1
Furthermore, we can compute the coordination number of our Lennard Jones atoms using:
ci =
X 1−
i6=j
1−
rij 8
1.5
rij 16
1.5
where rij __FILL__ is the distance between atom i and atom j . The following cell contains a skeleton input file for
PLUMED that gets it to calculate and print the values these two quantities take every 100 time steps to a file called
colvar.
BEGIN_PLUMED_FILE
c1: COORDINATIONNUMBER SPECIES=__FILL__ MOMENTS=__FILL__ SWITCH={RATIONAL __FILL__ }
PRINT ARG=__FILL__ FILE=colvar STRIDE=100
Copy and paste the content above into your plumed.dat file after the lines that you added in the previous
exercise that added the restraints to stop the cluster from evaporating. Fill in the blanks in the input above
and, once you have a working plumed.dat file, run a calculation using simplemd at a temperature of kB T =
0.2. Once you have generated the trajectory plot the time series of second and third moment values using
gnuplot or some other plotting package.
11.23.5.3.1
Extensions
Try the following exercises if you have time and if you wish to take this exercise further:
• Investigate how SPRINT coordinates are defined and calculated using PLUMED and try to compute them for
this particular system.
• Read about other collective variables that can be calculated using PLUMED. A topic that is particularly important to understand is how PLUMED deals with periodic boundary conditions.
Generated by Doxygen
836
Tutorials
11.23.5.4
Estimating the free energy surface
When you plotted the time series for the collective variables in the previous exercise you should have seen that the
values of these collective variables fluctuate around a number of different constant values for long periods of time.
There are then infrequent jumps and after these jumps the value of the collective variable settles down and begins
to fluctuate around a different constant value. There are jumps in the value of the CV whenever the system moves
from one minimums illustrated above to another. What we would ideally like to extract from our simulation are the
relative free energies of these various minimums. From elementary statistical mechanics, however, we know that
the free energy is given by:
F (s) = −kB T ln P (s)
Consequently, if we can extract an estimate of the probability that the CVs take particular values, s, then we can
get an estimate of the free energy. Extracting an estimate that for the probability that the collective variables take
a particular value is easy, however. We just need to construct a histogram from the CV values that the system
took during the trajectory. The following cell contains a skeleton input file for PLUMED that gets it to estimate this
histogram and that converts and outputs this estimate of the histogram to a file called fes.dat.
BEGIN_PLUMED_FILE
hh: HISTOGRAM __FILL__ __FILL__=-1.0,-1.0 __FILL__=1.5,1.5 GRID_BIN=300,300 __FILL__=DISCRETE STRIDE=100
fes: CONVERT_TO_FES GRID=_FILL__ __FILL__=0.2
DUMPGRID GRID=__FILL__ FILE=fes.dat
Copy and paste the content above into your plumed.dat file after the lines that you added in the previous
two exercises. Fill in the blanks in the input above and, once you have a working plumed.dat file, run a
calculation using simplemd at a temperature of kB T = 0.2. Once you have generated the trajectory create
a contour plot of the free energy surface that is contained in fes.dat using gnuplot or some other plotting
package.
The free energy surface that you get from this calculation should look something like the figure shown on the left
below. Please note that in order to fully sample configuration space and in order to get a reasonably converged
estimate of the free energy you are going to have to use many more time steps than you did in previous exercises.
The figure shown on the right is the free energy surface obtained if you run at a temperature of kB T = 0.1. As
you can see a much smaller volume of configuration space is explored at this lower temperature
Rerun the calculation of the free energy surface at a lower temperature. What differences do you observe
at the lower temperature? Why might these differences be problematic?
When you run the simulation at a lower temperature you should see that the system no longer explores all the basins
in the free energy landscape. If the temperature is sufficiently low the system will remain trapped in the original
configuration throughout the whole simulation run. At very low temperatures this may be the correct behavior and
the free energy estimate you obtain may prove to be a reasonable estimate. At the same time, however, lowering
the temperature makes the barrier crossing a rarer event. It thus becomes less likely that you will observe a
crossing between basins in a lower temperature simulation. The fact that the histogram shows that the probability
of observing these configurations is zero may thus simply be a consequence of the fact that the simulation is not
converged. The free energy will thus look like the one shown below instead of looking like the one in the previous
hidden section:
11.23.5.4.1
Extensions
Try the following exercises if you have time and if you wish to take this exercise further:
• Try to recalculate the free energy surface but use kernel density estimation when calculating the
HISTOGRAM.
• Work through Trieste tutorial: Averaging, histograms and block analysis and try to apply the ideas this tutorial
covers to calculate appropriate error bars the estimate of the free energy surface that you extracted in the
previous exercises.
Generated by Doxygen
11.23 ESDW Workshop Lyon 2019: A very simple introduction to PLUMED
11.23.5.5
837
Performing metadynamics
We can use an enhanced sampling algorithm to overcome the problems that we encountered at the end of the last
exercise and to more fully explore configuration space even at low temperature. In this final exercise we are thus
going to perform a metadynamics simulation on our Lennard Jones cluster. In metadynamics the system is forced
to explore more of configuration space by a history dependent bias that has the following functional form:
t
X
(s(t) − s(τ ))2
V (s, t) =
w(τ ) exp −
2σ 2
τ =0
This bias potential consists of a sum of Gaussian kernels with bandwidth σ that are centered at the values of the
CV that the system took at previous times. The weights of the kernels in this sum are time dependent because we
are going to use the well-tempered variant of metadynamics which introduces one further parameter γ = T +∆T
.
T
To run metadynamics on the Lennard Jones cluster that we have been studying in this exercise using PLUMED you
would delete the lines that you used to compute the histogram from the plumed input file that we have been using
thus far and you would add a line like the one shown below.
BEGIN_PLUMED_FILE
METAD ARG=__FILL__ HEIGHT=__FILL__ PACE=__FILL__ SIGMA=__FILL__ GRID_MIN=-1.5,-1.5 GRID_MAX=2.5,2.5 GRID_BIN=5
This input should be modified to instruct PLUMED to add Gaussian kernels with a bandwidth of 0.1 in both
the second and third moment of the distribution of coordination numbers and a height of 0.05 every 50 MD
steps. The metadynamics calculation should then be run using simplemd at a temperature of kB T = 0.1.
A nice feature of the metadynamics method is that, if the simulation is converged, the final bias potential is a related
to the underlying free energy surface by:
F (s) = −
T + ∆T
V (s, t)
∆T
This formula is implemented in the tool sum_hills that is part of the PLUMED package. To run sum_hills on the
output of your metadynamics simulation you can run the command:
plumed sum_hills --hills HILLS
This command should output a file called fes.dat that contains the final estimate of the free energy surface that was
calculated using metadynamics.
Try to run the sum_hills command on the HILLS file output by your metadynamics simulation. Visualize the
fes.dat file that is output by using gnuplot or some similar plotting package.
11.23.5.5.1
Extensions
Try the following exercises if you have time and if you wish to take this exercise further:
• Work through Trieste tutorial: Averaging, histograms and block analysis and try to apply the ideas this tutorial
covers to calculate an estimate of the free energy surface using metadynamics and reweighting.
• Try to estimate the errors on your estimate of the free energy surface.
Generated by Doxygen
838
11.23.6
Tutorials
Conclusions
This exercise has hopefully given you a sense of the sorts of calculations that can be performed using PLUM←ED. Hopefully you now have an understanding of how PLUMED input files are structured so that variables can be
passed between different actions. Furthermore, you should have seen how PLUMED can be used both to analyze
trajectories and to add in additional forces that force the system to undergo transitions that it would not otherwise
undergo.
Obviously, given the short time available to us in this tutorial, we have only scratched the surface in terms of what
PLUMED can be used to do and in terms of how metadynamics calculations are run in practice. If you want to
understand more about how to run PLUMED we would recommend that you start by reading the chapter that we
provided a link to in the introduction to this tutorial. For now though well done on completing the exercise and good
luck with your future PLUMED-related endeavors.
11.24
Moving from PLUMED 1 to PLUMED 2
Syntax in PLUMED 2 has been completely redesigned based on our experience using PLUMED 1, hopefully making
it clearer, more flexible, and less error prone. The main difference is that whereas in PLUMED 1 lines could be
inserted in any order, in PLUMED 2 the order of the lines matters. This is due to a major change in the internal
architecture of PLUMED. In version 2, commands (or "actions") are executed in the order they are found in the input
file. Because of this, you must e.g. first compute a collective variable and then print it later. More information can
be found in the Section about Getting Started.
Other important changes are in the way groups and units are used, as discussed below. Finally, many features
appear under a different name in the new version.
11.24.1
New syntax
We know that changing the input syntax requires a lot of work from the user side to update their input files. However,
we believe that the new syntax is easier to read and that it allows for more flexibility. As an example, something that
in PLUMED 1.3 was:
HILLS HEIGHT 0.4 W_STRIDE 600
WELLTEMPERED SIMTEMP 300 BIASFACTOR 15
RGYR LIST
all->
1
5 6 7
9 11 15 16 17 19
all
g1->
17 20 22 30
g1
LOOP 37 40
g2 gmx_mpi mdrun -s topolA.tpr -nsteps 10000
The nsteps flags can be used to change the number of time steps and topolA.tpr is the name of the tpr file. While
running, gromacs will produce an md.log file, with log information, and a traj.xtc file, with a binary trajectory. The
trajectory can be visualized with VMD using a command such as
> vmd confout.gro tra.xtc
To run a simulation with gromacs+plumed you just need to add a -plumed flag
> gmx_mpi mdrun -s topolA.tpr -nsteps 10000 -plumed plumed.dat
Here plumed.dat is the name of the plumed input file. Notice that PLUMED will write information in the md.log that
could be useful to verify if the simulation has been set up properly.
11.25.2.1.1
Exercise 0
In this exercise, we will run a plain molecular dynamics simulation and monitor the Φ and Ψ dihedral angles on the
fly. Using the following PLUMED input file you can monitor Φ and Ψ angles during the MD simulation
BEGIN_PLUMED_FILE
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
PRINT ARG=phi,psi STRIDE=100 FILE=colvar
Notice that PLUMED is going to compute the collective variables only when necessary, that is, in this case, every
100 steps. This is not very relevant for simple variables such as torsional angles, but provides a significant speedup
when using expensive collective variables.
PLUMED will write a textual file named colvar containing three columns: physical time, Φ and Ψ. Results can be
plotted using gnuplot:
> gnuplot
# this shows phi as a function of time
gnuplot> plot "colvar" u 2
# this shows psi as a function of time
gnuplot> plot "colvar" u 3
# this shows psi as a function of phi
gnuplot> plot "colvar" u 2:3
Now try to do the same using the two different initial configurations that we provided (topolA.tpr and topol←B.tpr). You can try both setup (water and vacuum). Results from 200ps (100000 steps) trajectories in vacuum
are shown in Figure munster-ala-traj.
Notice that the result depends heavily on the starting structure. For the simulation in vacuum, the two free-energy
minima are separated by a large barrier and, in such a short simulation, the system cannot cross it. In water the
barrier is smaller and you might see some crossing. Also notice that the two clouds are well separated, indicating
that these two collective variables are good enough to properly distinguish among the two minima.
As a final comment, notice that if you run twice the same calculation in the same directory, you might overwrite the
resulting files. GROMACS takes automatic backup of the output files, and PLUMED does it as well. In case you are
restarting a simulation, you can add the keyword RESTART at the beginning of the PLUMED input file. This will tell
PLUMED to append files instead of taking a backup copy.
Generated by Doxygen
844
11.25.2.2
Tutorials
Analyze using the driver
Imagine you already made a simulation, with or without PLUMED. You might want to compute the collective variables
a posteriori, from the trajectory file. You can do this by using the plumed executable on the command line. Type
> plumed driver --help
to have an idea of the possible options. See driver for the full documentation.
Here we will use the driver the compute Φ and Ψ on the already generated trajectory. Let's assume the trajectory
is named traj.xtc. You should prepare an PLUMED input file named analysis.dat as:
BEGIN_PLUMED_FILE
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
PRINT ARG=phi,psi FILE=analysis
Notice that typically when using the driver we do not provide a STRIDE keyword to PRINT. This implies "print at
every step" which, analyzing a trajectory, means "print for all the available snapshots". Then, you can use the
following command:
> plumed driver --mf_xtc traj.xtc --plumed analysis.dat
Notice that PLUMED has no way to now the value of physical time from the trajectory. If you want physical time to
be printed in the analysis file you should give more information to the driver, e.g.:
> plumed driver --mf_xtc traj.xtc --plumed analysis.dat --timestep 0.002 --trajectory-stride 1000
(see driver)
In this case we inform the driver that the traj.xtc file was produced in a run with a timestep of 0.002 ps and
saving a snap shot every 1000 time steps.
You might want to analyze a different collective variable, such as the gyration radius. The gyration radius tells how
extended is the molecules in space. You can do it with the following plumed input file
BEGIN_PLUMED_FILE
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
heavy: GROUP ATOMS=1,5,6,7,9,11,15,16,17,19
gyr: GYRATION ATOMS=heavy
# the same could have been achieved with
# gyr: GYRATION ATOMS=1,5,6,7,9,11,15,16,17,19
PRINT ARG=phi,psi,gyr FILE=analyze
Now try to compute the time series of the gyration radius.
Generated by Doxygen
11.25 Munster tutorial
11.25.2.3
845
Periodic boundaries and explicit water
In case you are running the simulation in water, you might see that at some point this variable shows some crazy
jump. The reason is that the trajectory contains coordinates where molecules are broken across periodic-boundary
conditions This happens with GROMACS and some other MD code. These codes typically have tools to process
trajectories and restore whole molecules. This trick is OK for the a-posteriori analysis we are trying now, but cannot
used when one needs to compute a collective variable on-the-fly or, as we will see later, one wants to add a bias
to that collective variable. For this reason, we implemented a workaround in PLUMED, that is the molecule should
be made whole using the WHOLEMOLECULES command. What this command is doing is making a loop over all
the atoms (in the order they are provided) and set the coordinates of each of them in the periodic image which is
as close as possible to the coordinates of the preceeding atom. In most cases it is sufficient to list all atoms of a
molecule in order. Look in the WHOLEMOLECULES page to get more information. Here this will be enough:
BEGIN_PLUMED_FILE
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
# notice the 1-22 syntax, a shortcut for a list 1,2,3,...,22
WHOLEMOLECULES ENTITY0=1-22
heavy: GROUP ATOMS=1,5,6,7,9,11,15,16,17,19
gyr: GYRATION ATOMS=heavy
PRINT ARG=phi,psi,gyr FILE=analyze
This is a very important issue that should be kept in mind when using PLUMED. Notice that starting with version 2.2
PLUMED will make molecules used in GYRATION (as well as in other variables) whole automatically, so that this
extra command will not be necessary.
Notice that you can instruct PLUMED to dump on a file not only the collective variables (as we are doing with PRINT)
but also the atomic positions. This is a very good way to understand what WHOLEMOLECULES is actually doing.
Try the following input
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=../TOPO/reference.pdb
DUMPATOMS FILE=test1.gro ATOMS=1-22
WHOLEMOLECULES ENTITY0=1-22
DUMPATOMS FILE=test2.gro ATOMS=1-22
DUMPATOMS writes on a gro file the coordinates of the alanine dipeptide atoms. Here PLUMED will produce
two files, one with coordinates before the application of WHOLEMOLECULES, and one with coordinates after∗ the
application of WHOLEMOLECULES. You can load both trajectories in VMD to see the difference. The MOLINFO
command is here used to provide atom names to PLUMED so that the resulting gro file looks nicer in VMD.
Notice that PLUMED has several commands that manipulate atomic coordinates.
One example is
WHOLEMOLECULES, that fixes problems with periodic boundary conditions. COM and CENTER add new
atoms, and FIT_TO_TEMPLATE can actually move atoms from their original position to align them on a template.
DUMPATOMS is this very useful to check what these commands are doing and for using the PLUMED driver to
manipulate MD trajectories.
11.25.2.4
Other analysis tools
PLUMED also allows you to make some analysis on the collective variables you are calculating. For example, you
can compute a histogram with an input like this one
Generated by Doxygen
846
Tutorials
BEGIN_PLUMED_FILE
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
heavy: GROUP ATOMS=1,5,6,7,9,11,15,16,17,19
gyr: GYRATION ATOMS=heavy
PRINT ARG=phi,psi,gyr FILE=analyze
HISTOGRAM ...
ARG=gyr
USE_ALL_DATA
KERNEL=discrete
GRID_MIN=0
GRID_MAX=1
GRID_BIN=50
GRID_WFILE=histogram
... HISTOGRAM
An histogram with 50 bins will be performed on the gyration radius. Try to compute the histogram for the Φ and Ψ
angles.
PLUMED can do much more than a histogram, more information on analysis can be found at the page Analysis
Notice that the plumed driver can also be used directly from VMD taking advantage of the PLUMED collective
variable tool developed by Toni Giorgino (http://multiscalelab.org/utilities/PlumedGUI). Just
open a recent version of VMD and go to Extensions/Analysis/Collective Variable Analysis (PLUMED). This graphical
interface can also be used to quickly build PLUMED input files based on template lines.
11.25.3
Biasing collective variables
We have seen that PLUMED can be used to compute collective variables. However, PLUMED is most often use
to add forces on the collective variables. To this aim, we have implemented a variety of possible biases acting on
collective variables. A bias works in a manner conceptually similar to the PRINT command, taking as argument
one or more collective variables. However, here the STRIDE is usually omitted (that is equivalent to setting it to 1),
which means that forces are applied at every timestep. In PLUMED 2.2 you will be able to change the STRIDE also
for bias potentials, but that's another story. In the following we will see how to apply harmonic restraints and how
to build an adaptive bias potential with metadynamics. The complete documentation for all the biasing methods
available in PLUMED can be found at the Bias page.
11.25.3.1
11.25.3.1.1
Metadynamics
Summary of theory
In metadynamics, an external history-dependent bias potential is constructed in the space of a few selected degrees
of freedom ~
s(q), generally called collective variables (CVs) [45]. This potential is built as a sum of Gaussian kernels
deposited along the trajectory in the CVs space:
V (~s, t) =
X
kτ gmx_mpi mdrun -s ../TOPO/topolA.tpr -plumed plumed.dat -nsteps 5000000
During the metadynamics simulation, PLUMED will create two files, named COLVAR and HILLS. The COLVAR file
contains all the information specified by the PRINT command, in this case the value of the CVs every 10 steps of
simulation, along with the current value of the metadynamics bias potential. We can use COLVAR to visualize the
behavior of the CV during the simulation:
By inspecting Figure munster-metad-phi-fig, we can see that the system is initialized in one of the two metastable
states of alanine dipeptide. After a while (t=0.1 ns), the system is pushed by the metadynamics bias potential to visit
the other local minimum. As the simulation continues, the bias potential fills the underlying free-energy landscape,
and the system is able to diffuse in the entire phase space.
The HILLS file contains a list of the Gaussian kernels deposited along the simulation. If we give a look at the header
of this file, we can find relevant information about its content:
Generated by Doxygen
11.25 Munster tutorial
#!
#!
#!
#!
#!
#!
849
FIELDS time phi psi sigma_phi sigma_psi height biasf
SET multivariate false
SET min_phi -pi
SET max_phi pi
SET min_psi -pi
SET max_psi pi
The line starting with FIELDS tells us what is displayed in the various columns of the HILLS file: the time of the
simulation, the value of phi and psi, the width of the Gaussian in phi and psi, the height of the Gaussian, and the bias
factor. We can use the HILLS file to visualize the decrease of the Gaussian height during the simulation, according
to the well-tempered recipe:
If we look carefully at the scale of the y-axis, we will notice that in the beginning the value of the Gaussian height is
higher than the initial height specified in the input file, which should be 1.2 kJ/mol. In fact, this column reports the
height of the Gaussian scaled by the pre-factor that in well-tempered metadynamics relates the bias potential to the
free energy. In this way, when we will use sum_hills, the sum of the Gaussian kernels deposited will directly provide
the free-energy, without further rescaling needed (see below).
One can estimate the free energy as a function of the metadynamics CVs directly from the metadynamics bias
potential. In order to do so, the utility sum_hills should be used to sum the Gaussian kernels deposited during the
simulation and stored in the HILLS file.
To calculate the free energy as a function of phi, it is sufficient to use the following command line:
> plumed sum_hills --hills HILLS
The command above generates a file called fes.dat in which the free-energy surface as function of phi is calculated
on a regular grid. One can modify the default name for the free energy file, as well as the boundaries and bin size
of the grid, by using the following options of sum_hills :
--outfile --min - the
--max - the
--bin - the
--spacing -
specify the outputfile for sumhills
lower bounds for the grid
upper bounds for the grid
number of bins for the grid
grid spacing, alternative to the number of bins
The result should look like this:
To assess the convergence of a metadynamics simulation, one can calculate the estimate of the free energy as a
function of simulation time. At convergence, the reconstructed profiles should be similar. The option –stride should
be used to give an estimate of the free energy every N Gaussian kernels deposited, and the option –mintozero can
be used to align the profiles by setting the global minimum to zero. If we use the following command line:
> plumed sum_hills --hills HILLS --stride 100 --mintozero
one free energy is calculated every 100 Gaussian kernels deposited, and the global minimum is set to zero in all
profiles. The resulting plot should look like the following:
To assess the convergence of the simulation more quantitatively, we can calculate the free-energy difference between the two local minima of the free energy along phi as a function of simulation time. We can use following script
to integrate the multiple free-energy profiles in the two basins defined by the following intervals in phi space: basin
A, -3min && $1min && $1 gmx_mpi mdrun -s ../TOPO/topolA.tpr -plumed plumed.dat -nsteps 5000000
As we did in the previous exercise, we can use COLVAR to visualize the behavior of the CV during the simulation.
Here we will plot at the same time the evolution of the metadynamics CV psi and of the other dihedral phi:
By inspecting Figure munster-metad-psi-phi-fig, we notice that something different happened compared to the previous exercise. At first the behavior of psi looks diffusive in the entire CV space. However, around t=1 ns, psi seems
trapped in a region of the CV space in which it was previously diffusing without problems. The reason is that the
non-biased CV phi after a while has jumped into a different local minima. Since phi is not directly biased, one has to
wait for this (slow) degree of freedom to equilibrate before the free energy along psi can converge. Try to repeat the
analysis done in the previous exercise (calculate the estimate of the free energy as a function of time and monitor
the free-energy difference between basins) to assess the convergence of this metadynamics simulation.
11.25.3.2
11.25.3.2.1
Restraints
Biased sampling theory
A system at temperature T samples conformations from the canonical ensemble:
P (q) ∝ e
U (q)
BT
−k
. Here q are the microscopic coordinates and kB is the Boltzmann constant. Since q is a highly dimensional
vector, it is often convenient to analyze it in terms of a few collective variables (see Belfast tutorial: Analyzing CVs
, Belfast tutorial: Adaptive variables I , and Belfast tutorial: Adaptive variables II ). The probability distribution for a
CV s is
Z
P (s) ∝
U (q)
BT
−k
dqe
δ(s − s(q))
This probability can be expressed in energy units as a free energy landscape F (s):
F (s) = −kB T log P (s)
.
Now we would like to modify the potential by adding a term that depends on the CV only. That is, instead of using
U (q), we use U (q) + V (s(q)). There are several reasons why one would like to introduce this potential. One is
to avoid that the system samples some un-desired portion of the conformational space. As an example, imagine
that you want to study dissociation of a complex of two molecules. If you perform a very long simulation you will
be able to see association and dissociation. However, the typical time required for association will depend on the
size of the simulation box. It could be thus convenient to limit the exploration to conformations where the distance
between the two molecules is lower than a given threshold. This could be done by adding a bias potential on the
distance between the two molecules. Another example is the simulation of a portion of a large molecule taken out
from its initial context. The fragment alone could be unstable, and one might want to add additional potentials to
keep the fragment in place. This could be done by adding a bias potential on some measure of the distance from
the experimental structure (e.g. on root-mean-square deviation).
Whatever CV we decide to bias, it is very important to recognize which is the effect of this bias and, if necessary,
remove it a posteriori. The biased distribution of the CV will be
P 0 (s) ∝
Z
−
dqe
U (q)+V (s(q))
kB T
δ(s − s(q)) ∝ e
−
V (s(q))
kB T
P (s)
and the biased free energy landscape
F 0 (s) = −kB T log P 0 (s) = F (s) + V (s) + C
Thus, the effect of a bias potential on the free energy is additive. Also notice the presence of an undetermined
constant C . This constant is irrelevant for what concerns free-energy differences and barriers, but will be important
Generated by Doxygen
852
Tutorials
later when we will learn the weighted-histogram method. Obviously the last equation can be inverted so as to obtain
the original, unbiased free-energy landscape from the biased one just subtracting the bias potential
F (s) = F 0 (s) − V (s) + C
Additionally, one might be interested in recovering the distribution of an arbitrary observable. E.g., one could
add a bias on the distance between two molecules and be willing to compute the unbiased distribution of some
torsional angle. In this case there is no straightforward relationship that can be used, and one has to go back to the
relationship between the microscopic probabilities:
P (q) ∝ P 0 (q)e
V (s(q))
kB T
The consequence of this expression is that one can obtained any kind of unbiased information from a biased
simulation just by weighting every sampled conformation with a weight
w∝e
V (s(q))
kB T
That is, frames that have been explored in spite of a high (disfavoring) bias potential V will be counted more than
frames that has been explored with a less disfavoring bias potential.
11.25.3.2.2
Umbrella sampling theory
Often in interesting cases the free-energy landscape has several local minima. If these minima have free-energy
differences that are on the order of a few times kB T they might all be relevant. However, if they are separated by
a high saddle point in the free-energy landscape (i.e. a low probability region) than the transition between one and
the other will take a lot of time and these minima will correspond to metastable states. The transition between one
minimum and the other could require a time scale which is out of reach for molecular dynamics. In these situations,
one could take inspiration from catalysis and try to favor in a controlled manner the conformations corresponding to
the transition state.
Imagine that you know since the beginning the shape of the free-energy landscape F (s) as a function of one CV s.
If you perform a molecular dynamics simulation using a bias potential which is exactly equal to −F (s), the biased
free-energy landscape will be flat and barrierless. This potential acts as an "umbrella" that helps you to safely cross
the transition state in spite of its high free energy.
It is however difficult to have an a priori guess of the free-energy landscape. We will see later how adaptive
techniques such as metadynamics (Belfast tutorial: Metadynamics) can be used to this aim. Because of this reason,
umbrella sampling is often used in a slightly different manner.
Imagine that you do not know the exact height of the free-energy barrier but you have an idea of where the barrier
is located. You could try to just favor the sampling of the transition state by adding a harmonic restraint on the CV,
e.g. in the form
V (s) =
k
(s − s0 )2
2
. The sampled distribution will be
P 0 (q) ∝ P (q)e
−k(s(q)−s0 )2
2kB T
For large values of k , only points close to s0 will be explored. It is thus clear how one can force the system to explore
only a predefined region of the space adding such a restraint. By combining simulations performed with different
values of s0 , one could obtain a continuous set of simulations going from one minimum to the other crossing the
transition state. In the next section we will see how to combine the information from these simulations.
If you want to just bring a collective variables to a specific value, you can use a simple restraint. Let's imagine that
we want to force the Φ angle to visit a region close to Φ = π/2. We can do it adding a restraint in Φ, with the
following input
Generated by Doxygen
11.25 Munster tutorial
853
BEGIN_PLUMED_FILE
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
res: RESTRAINT ARG=phi AT=0.5pi KAPPA=5
PRINT ARG=phi,psi,res.bias
Notice that here we are printing a quantity named res.bias. We do this because RESTRAINT does not define
a single value (that here would be theoretically named res) but a structure with several components. All biasing
methods (including METAD) do so, as well as many collective variables (see e.g. DISTANCE used with COMP←ONENTS keyword). Printing the bias allows one to know how much a given snap shot was penalized. Also notice
that PLUMED understands numbers in the for {number}pi. This is convenient when using torsions, since they
are expressed in radians.
Now you can plot your trajectory with gnuplot and see the effect of KAPPA. You can also try different values of
KAPPA. The stiffer the restraint, the less the collective variable will fluctuate. However, notice that a too large kappa
could make the MD integrator unstable.
11.25.3.3
Moving restraints
A restraint can also be modified as a function of time. For example, if you want to bring the system from one
minimum to the other, you can use a moving restraint on Φ:
BEGIN_PLUMED_FILE
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
# notice that a long line can be splitted with this syntax
MOVINGRESTRAINT ...
# also notice that a LABEL keyword can be used and is equivalent
# to adding the name at the beginning of the line with colon, as we did so far
LABEL=res
ARG=phi
STEP0=0 AT0=-0.5pi KAPPA0=5
STEP1=10000 AT0=0.5pi
...
PRINT ARG=phi,psi,res.work,res.phi_cntr FILE=colvar
Notice that here we are plotting a few new components, namely work and phi_cntr. The former gives the work
performed in pulling the restraint, and the latter the position of the restraint. Notice that if pulling is slow enough one
can compute free energy profile from the work. You can plot the putative free-energy landscape with
> gnuplot
# column 5 is res.phi_cntr
# column 4 is res.work
gnuplot> p "colvar" u 5:4
11.25.3.4
Using multiple replicas
Warning
Notice that multireplica simulations with PLUMED are fully supported with GROMACS, but only partly supported with other MD engines.
Some free-energy methods are intrinsically parallel and requires running several simultaneous simulations. This can
be done with gromacs using the multi replica framework. That is, if you have 4 tpr files named topol0.tpr, topol1.tpr,
topol2.tpr, topol3.tpr you can run 4 simultaneous simulations.
> mpirun -np 4 gmx_mpi mdrun -s topol.tpr -plumed plumed.dat -multi 4 -nsteps 500000
Generated by Doxygen
854
Tutorials
Each of the 4 replicas will open a different topol file, and GROMACS will take care of adding the replica number
before the .tpr suffix. PLUMED deals with the extra number in a slightly different way. In this case, for example,
PLUMED first look for a file named plumed.dat.X, where X is the number of the replica. In case the file is not
found, then PLUMED looks for plumed.dat. If also this is not found, PLUMED will complain. As a consequence,
if all the replicas should use the same input file it is sufficient to put a single plumed.dat file, but one has also
the flexibility of using separate files named plumed.dat.0, plumed.dat.1 etc. Finally, notice that the way
PLUMED adds suffixes will change in version 2.2, and names will be plumed.0.dat etc.
Also notice that providing the flag -replex one can instruct gromacs to perform a replica exchange simulation.
Namely, from time to time gromacs will try to swap coordinates among neighboring replicas and accept of reject the
exchange with a Monte Carlo procedure which also takes into account the bias potentials acting on the replicas,
even if different bias potentials are used in different replicas. That is, PLUMED allows to easily implement many
forms of Hamiltonian replica exchange.
11.25.3.5
11.25.3.5.1
Using multiple restraints with replica exchange
Weighted histogram analysis method theory
Let's now consider multiple simulations performed with restraints located in different positions. In particular, we will
consider the i-th bias potential as Vi . The probability to observe a given value of the collective variable s is:
Pi (s) = R
P (s)e
V (s)
BT
ds0 P (s0 )e
−
V (s)
BT
− ki
− ki
P (s)e
=
Zi
Vi (s0 )
kB T
where
Zi =
X
e−(U (q)+Vi (q))
q
The likelyhood for the observation of a sequence of snapshots qi (t) (where i is the index of the trajectory and t
is time) is just the product of the probability of each of the snapshots. We use here the minus-logarithm of the
likelihood (so that the product is converted to a sum) that can be written as
L=−
XZ
dt log Pi (si (t)) =
Vi (si (t))
dt − log P (si (t)) +
+ log Zi
kB T
XZ
i
i
δL
δP (s)
= 0. After some boring algebra the following expression
V (s)
− ki T
XZ
B
δsi (t),s
e
0=
+
dt −
P
(s)
Zi
i
One can then maximize the likelyhood by setting
can be obtained
In this equation we aim at finding P (s). However, also the list of normalization factors Zi is unknown, and they
should be found selfconsistently. Thus one can find the solution as
N (s)
P (s) ∝
P R
i
dt e
−
Vi (s)
kB T
Zi
where Z is selfconsistently determined as
Z
Zi ∝
ds0 P (s0 )e
−
Vi (s0 )
kB T
These are the WHAM equations that are traditionally solved to derive the unbiased probability P (s) by the combination of multiple restrained simulations. To make a slightly more general implementation, one can compute the
weights that should be assigned to each snapshot, that turn out to be:
wi (t) ∝ P R
j
1
−βVj (si (t))
dt e Zj
Generated by Doxygen
11.25 Munster tutorial
855
The normalization factors can in turn be found from the weights as
P R
Zi ∝
j
dte−βVi (sj (t)) wj (t)
P R
dtwj (t)
j
This allows to straighforwardly compute averages related to other, non-biased degrees of freedom, and it is thus
a bit more flexible. It is sufficient to precompute this factors w and use them to weight every single frame in the
trajectory.
11.25.3.5.2
Exercise 4
In this exercise we will run multiple restraint simulations and learn how to reweight and combine data with WHAM to
obtain free-energy profiles. We start with running in a replica-exchange scheme 32 simulations with a restraint on
phi in different positions, ranging from -3 to 3. We will instruct gromacs to attempt an exchange between different
simulations every 1000 steps.
nrep=32
dx=‘echo "6.0 / ( $nrep - 1 )" | bc -l‘
for((i=0;iplumed.dat.$i << EOF
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
#
# Impose an umbrella potential on phi
# with a spring constant of 200 kjoule/mol
# and centered in phi=AT
#
restraint-phi: RESTRAINT ARG=phi KAPPA=200.0 AT=$AT
# monitor the two variables and the bias potential
PRINT STRIDE=100 ARG=phi,psi,restraint-phi.bias FILE=COLVAR
EOF
# we initialize some replicas in A and some in B:
if((i%2==0)); then
cp ../TOPO/topolA.tpr topol$i.tpr
else
cp ../TOPO/topolB.tpr topol$i.tpr
fi
done
# run REM
mpirun -np $nrep gmx_mpi mdrun -plumed plumed.dat -s topol.tpr -multi $nrep -replex 1000 -nsteps 500000
To be able to combine data from all the simulations, it is necessary to have an overlap between statistics collected
in two adjacent umbrellas.
Have a look at the plot of (phi,psi) for the different simulations to understand what is happening.
An often misunderstood fact about WHAM is that data of the different trajectories can be mixed and it is not necessary to keep track of which restraint was used to produce every single frame. Let's get the concatenated trajectory
> trjcat_mpi -cat -f traj*.xtc -o alltraj.xtc
Now we should compute the value of each of the bias potentials on the entire (concatenated) trajectory.
Generated by Doxygen
856
Tutorials
nrep=32
dx=‘echo "6.0 / ( $nrep - 1 )" | bc -l‘
for i in ‘seq 0 $(( $nrep - 1 ))‘
do
# center of the restraint
AT=‘echo "$i * $dx - 3.0" | bc -l‘
cat >plumed.dat << EOF
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
restraint-phi: RESTRAINT ARG=phi KAPPA=200.0 AT=$AT
# monitor the two variables and the bias potential
PRINT STRIDE=100 ARG=phi,psi,restraint-phi.bias FILE=ALLCOLVAR.$i
EOF
plumed driver --mf_xtc alltraj.xtc --trajectory-stride=10 --plumed plumed.dat
done
It is very important that this script is consistent with the one used to generate the multiple simulations above. Now,
single files named ALLCOLVAR.XX will contain on the fourth column the value of the bias centered in a given
position, computed on the entire concatenated trajectory.
Next step is to compute the weights self-consistently solving the WHAM equations, using the python script "wham.←py" contained in the SCRIPTS directory. To use this code:
> ../SCRIPTS/wham.sh ALLCOLVAR.*
This script will produce several files. Let's visualize "phi_fes.dat", which contains the free energy as a function of
phi, and compare this with the result previously obtained with metadynamics.
11.25.3.5.3
Exercise 5
In the previous exercise, we use multiple restraint simulations to calculate the free energy as a function of the
dihedral phi. The resulting free energy was in excellent agreement with our previous metadynamics simulation. In
this exercise we will repeat the same procedure for the dihedral psi. At the end of the steps defined above, we
can plot the free energy "psi_fes.dat" and compare it with the reference profile calculated from a metadynamics
simulations using both phi and psi as CVs.
We can easily spot from the plot above that something went wrong in this multiple restraint simulations, despite we
used the very same approach we adopted for the phi dihedral. The problem here is that psi is a "bad" collective
variable, and the system is not able to equilibrate the missing slow degree of freedom phi in the short time scale of
the umbrella simulation (1 ns). In the metadynamics exercise in which we biased only psi, we detect problems by
observing the behavior of the CV as a function of simulation time. How can we detect problems in multiple restraint
simulations? This is slightly more complicated, but running this kind of simulation in a replica-exchange scheme
offers a convenient way to detect problems.
The first thing we need to do is to demux the replica-exchange trajectories and reconstruct the continous trajectories
of the replicas across the different restraint potentials. In order to do so, we can use the following script:
> demux.pl md0.log
> trjcat_mpi -f traj*.xtc
-demux replica_index.xvg
This commands will generate 32 continous trajectories, named XX_trajout.xtc. We will use the driver to calculate
the value of the CVs phi and psi on these trajectories.
Generated by Doxygen
11.26 Optimizing PLUMED performance
857
nrep=32
for i in ‘seq 0 $(( $nrep - 1 ))‘
do
cat >plumed.dat << EOF
phi: TORSION ATOMS=5,7,9,15
psi: TORSION ATOMS=7,9,15,17
# monitor the two variables
PRINT STRIDE=100 ARG=phi,psi FILE=COLVARDEMUX.$i
EOF
plumed driver --mf_xtc ${i}_trajout.xtc --trajectory-stride=10 --plumed plumed.dat
done
The COLVARDEMUX.XX files will contain the value of the CVs on the demuxed trajectory. If we visualize these
files we will notice that replicas sample the CVs space differently. In order for each umbrella to equilibrate the slow
degrees of freedom phi, the continuous replicas must be ergodic and thus sample the same distribution in phi and
psi.
11.26
Optimizing PLUMED performance
Authors
Giovanni Bussi
Date
February 19, 2019
This document describes the PLUMED tutorial held at CINECA, February 2019. The aim of this tutorial is to learn
how to optimize simulations performed using PLUMED. Although the presented input files are correct, the users are
invited to refer to the literature to understand how the parameters of enhanced sampling methods should be
chosen in a real application.
Users are also encouraged to follow the links to the full PLUMED reference documentation and to wander around
in the manual to discover the many available features and to do the other, more complete, tutorials.
11.26.1
How to optimize a simulation performed with PLUMED
The input files for this exercise can be found in thisTARBALL .
We will now learn how to optimize a simulation where PLUMED is used on-the-fly to compute or bias collective
variables. You should use the provided topol.tpr file.
11.26.1.1
Run a simulation with GROMACS alone
In order to run a simulation with gromacs you can use the following command
gmx_mpi mdrun -nsteps 500 -v -nb cpu -ntomp 12 -pin on
This will run a simulation for 500 steps, without using any GPU-acceleration, and with 12 OpenMP threads. Later at
the end of the tutorial we will see how the speed of GROMACS+PLUMED changes when using the GPU. Adjust the
number of threads based on the number of processors that you have on each node. 500 steps should be sufficient
to get an estimate of the simulation speed if you use OpenMP only. Notice that if you use MPI parallelism with
GROMACS more steps are needed due to dynamic load balancing.
As a first step, make a table showing the performance (ns per day) with different number of OpenMP threads. On
my workstation the result is
Generated by Doxygen
858
Tutorials
Number of threads
Performance (ns/day)
Wallclock time (s)
12
6
3
1
27.225
12.677
8.827
3.685
3.180
6.829
9.807
23.491
Scaling is approximately linear.
11.26.1.2
Run a simulation with GROMACS+PLUMED
Now you can run GROMACS with PLUMED using the following input file
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=conf.pdb
# @water and @hydrogens are special groups introduce in PLUMED 2.5!
wat: GROUP ATOMS=@water
ow: GROUP ATOMS=@water REMOVE=@hydrogens
mg: GROUP ATOMS=10484
p:
GROUP ATOMS=@P-2
dp:
DISTANCE ATOMS=mg,p
cn:
COORDINATION GROUPA=mg GROUPB=ow R_0=0.261
PRINT ARG=dp,cn
The command to run the simulation will be
gmx_mpi mdrun -nsteps 500 -v -nb cpu -ntomp 12 -pin on -plumed plumed.dat
The total time required by this simulation should increase. This is because PLUMED occupies some of the CPU
cycles in order to:
• copy the coordinates of the requested atoms
• compute the requested collective variables
• print them on a file
Take note of the increment in the wall-clock time. On my workstation it is approx 1.5 seconds more for these 500
steps with 12 OpenMP threads. Check how much is the impact when you change the number of threads.
11.26.1.3
Timing individual variables
In order to know which of your collective variables is taking more time to be computed, you should use the DEBUG
DETAILED_TIMERS flag (place it after MOLINFO). The end of the md.log file should now look similar to this
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
PLUMED:
1 Prepare dependencies
2 Sharing data
3 Waiting for data
4 Calculating (forward loop)
4A 1 @1
4A 6 dp
4A 7 cn
4A 8 @8
5 Applying (backward loop)
5A 0 @8
5A 1 cn
5A 2 dp
5A 7 @1
5B Update forces
6 Update
1
501
501
501
501
501
501
501
501
501
501
501
501
501
501
501
1.138360
0.001654
0.052691
0.004488
0.444763
0.001294
0.007342
0.422879
0.001087
0.112352
0.000713
0.069576
0.002932
0.000806
0.029823
0.009887
1.138360
0.000003
0.000105
0.000009
0.000888
0.000003
0.000015
0.000844
0.000002
0.000224
0.000001
0.000139
0.000006
0.000002
0.000060
0.000020
1.138360
0.000003
0.000092
0.000008
0.000849
0.000002
0.000013
0.000807
0.000002
0.000210
0.000001
0.000132
0.000005
0.000001
0.000050
0.000017
Notice that running with DETAILED_TIMERS might slow down a bit more your simulation.
Each line tells you how expensive was the calculation of each collective variable. Find which is the most expensive!
We will focus on it in the next points
Generated by Doxygen
1.1383
0.0000
0.0048
0.0000
0.0018
0.0000
0.0000
0.0017
0.0000
0.0021
0.0000
0.0003
0.0000
0.0000
0.0019
0.0001
11.26 Optimizing PLUMED performance
11.26.1.4
859
Optimizing coordination numbers using neighbor lists
The COORDINATION of multiple atoms can be very expensive for a number of reasons:
• It might require the calculation of a large number of distances
• It might require many atoms to be copied from GROMACS to PLUMED
In this specific example, the coordination number will require a number of calculations that is proportional to the
number of water molecules in the system.
Repeat the timing above using neighbor lists. Here's how you should modify the line computing the COORDINA←TION in order to enable neighbor lists
BEGIN_PLUMED_FILE
cn:
COORDINATION GROUPA=mg GROUPB=ow R_0=0.261 NLIST NL_STRIDE=20 NL_CUTOFF=1.0
There are two critical parameters:
• the stride for the neighbor lists (here 20 steps).
• the cutoff distance (here 1 nm).
You should be very careful since using neighbor lists introduces approximations that might invalidate your calculation! The recommended procedure is to first perform a simulation where you compute your variable with different
settings and compare the result. For instance:
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=conf.pdb
wat: GROUP ATOMS=@water
ow: GROUP ATOMS=@water REMOVE=@hydrogens
mg: GROUP ATOMS=10484
p:
GROUP ATOMS=@P-2
dp:
DISTANCE ATOMS=mg,p
cn:
COORDINATION GROUPA=mg GROUPB=ow R_0=0.261
# use increasing values of the stride
cn2:
COORDINATION GROUPA=mg GROUPB=ow R_0=0.261 NLIST NL_STRIDE=2 NL_CUTOFF=1.0
cn10:
COORDINATION GROUPA=mg GROUPB=ow R_0=0.261 NLIST NL_STRIDE=10 NL_CUTOFF=1.0
cn20:
COORDINATION GROUPA=mg GROUPB=ow R_0=0.261 NLIST NL_STRIDE=20 NL_CUTOFF=1.0
cn50:
COORDINATION GROUPA=mg GROUPB=ow R_0=0.261 NLIST NL_STRIDE=50 NL_CUTOFF=1.0
# notice that here we are using a regular expression to select all coordination numbers
PRINT ARG=dp,(cn.*) FILE=COLVAR STRIDE=1
In the COLVAR files you will see multiple columns corresponding to values computed using different strides. You
should pick a column such that the reported value is not too different from the one in the third column (that is:
without neighbor lists). "Not too different" of course depends on how much you want to trade in accuracy vs speed.
Warning
As of PLUMED 2.5, the construction of the neighbor list is not parallelized! As a consequence, the advantage
of using it might be not compensated by the slow time required to construct it. This might change in a future
PLUMED version. In addition, notice that the time for constructing the list is not present in the breakdown of
the timers seen above, but is part of the "Prepare dependencies" stage.
Once you picked a setting that gives you results that are accurate enough, you can measure the speed using that
setting alone using an input where only that specific setting is used. You will probably see that using neighbor lists
is usually inconvenient unless you run with a single or very few cores.
Generated by Doxygen
860
Tutorials
11.26.1.5
Biasing your CVs: multiple time stepping
So far we have used PLUMED to analyze a CV on the fly. In principle, when you analyze CVs you typically only
print them with a given stride (say, every 100 steps). This of course moderates significantly their cost. However,
when you bias a CV you typically need to compute it at every step. Let's say that you want to use a restraint to make
sure that the Mg ion is always six coordinated with water. This can be obtained using a RESTRAINT located AT=6.
Remove the PRINT action from your input file and replace it with the following actions:
BEGIN_PLUMED_FILE
# apply a restraint. this will be computed at every step by default
RESTRAINT ARG=cn AT=6 KAPPA=5.0
# only print every 100 steps
PRINT ARG=dp,cn FILE=COLVAR STRIDE=100
Now measure the speed of your simulation. You should see some overhead due to PLUMED. You can now try to
use multiple-time-stepping [112]}. To do so add a STRIDE option to the RESTRAINT line. You can also use the
EFFECTIVE_ENERGY_DRIFT action to print a kind of "total energy drift" due to the application of the PLUMED
bias. In molecular dynamics simulation you usually monitor the drift in the total energy in order to choose the time
step. Here you can use the value of the effective energy drift to choose the stride for multiple-time-stepping.
BEGIN_PLUMED_FILE
RESTRAINT ARG=cn AT=6 KAPPA=5.0 STRIDE=2
EFFECTIVE_ENERGY_DRIFT PRINT_STRIDE=100 FILE=eff
Using a STRIDE=5 you should get something like this
#! FIELDS
0.000000
0.200000
0.400000
0.600000
0.800000
1.000000
time effective-energy
0.000000
0.012010
0.024574
0.105866
0.178739
0.254018
The effective energy will drift quickly! Using a STRIDE=2 instead the effective energy will be very stable
#! FIELDS
0.000000
0.200000
0.400000
0.600000
0.800000
1.000000
time effective-energy
0.000000
0.000980
0.000041
-0.000162
0.000078
-0.000395
Note
The STRIDE option is not included in the manual, but can be used for all the bias actions to activate multipletime-stepping.
11.26.1.6
Using grids in metadynamics
Let's try to perform a metadynamics simulation biasing the coordination number and the distance between the
magnesium ion and the phosphate. Parameters are similar to those used in [101]}, although we use here a shorter
deposition pace in order to artificially increase the computational cost.
Generated by Doxygen
11.26 Optimizing PLUMED performance
861
BEGIN_PLUMED_FILE
MOLINFO STRUCTURE=conf.pdb
wat: GROUP ATOMS=@water
ow: GROUP ATOMS=@water REMOVE=@hydrogens
mg: GROUP ATOMS=10484
p:
GROUP ATOMS=@P-2
dp:
DISTANCE ATOMS=mg,p
cn:
COORDINATION GROUPA=mg GROUPB=ow R_0=0.261
metadP: METAD ARG=dp,cn SIGMA=0.05,0.1 HEIGHT=0.3 PACE=100 TEMP=300 BIASFACTOR=15
PRINT ARG=dp,cn FILE=COLVAR STRIDE=100
If you use this input for a very long simulation you will realize that most of the time is spent within the METAD
action. The reason is simple: in its standard implementation, metadynamics is implemented as a history dependent
potential where, every time we need to compute the force, a sum over the past history is performed. The history is
saved in the HILLS file (have a look at it). When this file becomes too large the simulation will slow down. Without
the need to run a very long simulation, we can see the problem by artificially creating a very long HILLS file. Every
line of the HILLS file contains:
• The value of time.
• The coordinates at which the Gaussian function was deposited.
• The width of the deposited Gaussian function
• The height
• A number called bias-factor (check METAD manual to know what it means).
We can make an artificially long HILLS file and then use it to restart our simulation.
var="$(
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.5
Linearized : No
Page Count : 918
Page Mode : UseOutlines
Author :
Title :
Subject :
Creator : LaTeX with hyperref package
Producer : pdfTeX-1.40.14
Create Date : 2019:04:12 12:38:30Z
Modify Date : 2019:04:12 12:38:30Z
Trapped : False
PTEX Fullbanner : This is pdfTeX, Version 3.1415926-2.5-1.40.14 (TeX Live 2013/Debian) kpathsea version 6.1.1
EXIF Metadata provided by EXIF.tools