Manual

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 532

Download
Open PDF In Browser	View PDF

PLUMED
2.3.4

Generated by Doxygen 1.8.14

Contents

Introduction

1.1

About this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1.2

Codes interfaced with PLUMED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Change Log

2.1

Version 2.0

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.2

Version 2.1

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.3

Version 2.2

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.4

Version 2.3

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Installation

3.1

Configuring PLUMED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.1.1

BLAS and LAPACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.1.2

VMD trajectory plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.2

Compiling PLUMED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.3

Installing PLUMED

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.4

Patching your MD code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.5

Cross compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.6

Installing PLUMED with MacPorts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.7

Installing PLUMED on a cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.8

Other hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.9

Code specific notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.9.1

amber14

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.9.2

gromacs-2016.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.9.3

gromacs-4.5.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.9.4

gromacs-5.0.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.9.5

gromacs-5.1.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.9.6

lammps-6Apr13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.9.7

namd-2.8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.9.8

namd-2.9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.9.9

qespresso-5.0.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CONTENTS

Getting started

4.1

Plumed units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4.2

UNITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Collective variables

5.1

Groups and Virtual Atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.1

Specifying Atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.1.1

Molecules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.1.2

Broken Molecules and PBC . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.2

Virtual Atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.3

GROUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.4

MOLINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.5

WHOLEMOLECULES

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.6

FIT_TO_TEMPLATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.7

WRAPAROUND

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.8

RESET_CELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.9

CENTER_OF_MULTICOLVAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.10 CENTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.11 COM

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.12 FIXEDATOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.13 GHOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CV Documentation

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.1

ALPHABETA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.2

ALPHARMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.3

ANGLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.4

ANTIBETARMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.5

CELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.6

CONSTANT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.7

CONTACTMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.8

COORDINATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.9

CS2BACKBONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2

Generated by Doxygen

CONTENTS

iii

5.2.10 DHENERGY

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.12 DIPOLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.13 DISTANCE_FROM_CONTOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.14 DISTANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.15 ENERGY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.16 ERMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.17 FAKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.18 FRET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.19 GPROPERTYMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.20 GYRATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.21 JCOUPLING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.22 NOE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.23 PARABETARMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2.11 DIHCOR

5.2.24 PATHMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
5.2.25 PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
5.2.26 PCAVARS

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

5.2.27 POSITION

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

5.2.28 PRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
5.2.29 PROPERTYMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
5.2.30 PUCKERING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
5.2.31 RDC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
5.2.32 TEMPLATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
5.2.33 TORSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
5.2.34 VOLUME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
5.3

Distances from reference configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
5.3.1

DRMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

5.3.2

MULTI-RMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

5.3.3

PCARMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

5.3.4

RMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Generated by Doxygen

CONTENTS

5.3.5
5.4

TARGET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
5.4.1

COMBINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

5.4.2

ENSEMBLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

5.4.3

FUNCPATHMSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

5.4.4

FUNCSUMHILLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

5.4.5

LOCALENSEMBLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

5.4.6

MATHEVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
5.4.6.1

5.5

TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

5.4.7

PIECEWISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

5.4.8

SORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

5.4.9

STATS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

MultiColvar

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

5.5.1

MultiColvar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

5.5.2

MultiColvar bias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

5.5.3

ANGLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

5.5.4

BRIDGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

5.5.5

COORDINATIONNUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

5.5.6

DENSITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

5.5.7

DISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

5.5.8

FCCUBIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

5.5.9

INPLANEDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

5.5.10 MOLECULES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.5.11 PLANES

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

5.5.12 Q3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
5.5.13 Q4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
5.5.14 Q6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
5.5.15 SIMPLECUBIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
5.5.16 TETRAHEDRAL

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

5.5.17 TORSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Generated by Doxygen

CONTENTS

5.5.18 XDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
5.5.19 XYDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
5.5.20 XZDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
5.5.21 YDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
5.5.22 YZDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
5.5.23 ZDISTANCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
5.5.24 MFILTER_BETWEEN

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

5.5.25 MFILTER_LESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
5.5.26 MFILTER_MORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
5.5.27 AROUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
5.5.28 CAVITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
5.5.29 INCYLINDER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
5.5.30 INSPHERE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
5.5.31 TETRAHEDRALPORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
5.5.32 GRADIENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
5.5.33 INTERMOLECULARTORSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
5.5.34 LOCAL_AVERAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
5.5.35 LOCAL_Q3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
5.5.36 LOCAL_Q4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
5.5.37 LOCAL_Q6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
5.5.38 NLINKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
5.5.39 SMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
5.5.40 MTRANSFORM_BETWEEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
5.5.41 MTRANSFORM_LESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
5.5.42 MTRANSFORM_MORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
5.5.43 UWALLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
5.6

Exploiting contact matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
5.6.1

ALIGNED_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

5.6.2

CONTACT_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

5.6.3

HBOND_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

5.6.4

SMAC_MATRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

5.6.5

CLUSTER_WITHSURFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

5.6.6

COLUMNSUMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

5.6.7

DFSCLUSTERING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

5.6.8

ROWSUMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

5.6.9

SPRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

5.6.10 CLUSTER_DIAMETER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
5.6.11 CLUSTER_DISTRIBUTION

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

5.6.12 CLUSTER_NATOMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
5.6.13 CLUSTER_PROPERTIES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
5.6.14 OUTPUT_CLUSTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Generated by Doxygen

CONTENTS

Analysis

289

6.1

Dimensionality Reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

6.2

COMMITTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

6.3

DUMPATOMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

6.4

DUMPDERIVATIVES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

6.5

DUMPFORCES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

6.6

DUMPMASSCHARGE

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

6.7

DUMPMULTICOLVAR

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

6.8

DUMPPROJECTIONS

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

6.9

PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
6.9.1

FLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

6.10 UPDATE_IF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
6.11 REWEIGHT_BIAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
6.12 REWEIGHT_METAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
6.13 REWEIGHT_TEMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
6.14 AVERAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
6.15 HISTOGRAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
6.16 MULTICOLVARDENS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
6.17 CONVERT_TO_FES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
6.18 DUMPCUBE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
6.19 DUMPGRID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
6.20 FIND_CONTOUR_SURFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
6.21 FIND_CONTOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
6.22 FIND_SPHERICAL_CONTOUR

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

6.23 FOURIER_TRANSFORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
6.24 INTERPOLATE_GRID

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

6.25 CLASSICAL_MDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
6.25.1 Method of optimisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
6.26 PCA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Generated by Doxygen

CONTENTS

vii

Bias

329

7.1

ABMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

7.2

BIASVALUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

7.3

EXTENDED_LAGRANGIAN

7.4

EXTERNAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

7.5

LOWER_WALLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

7.6

METAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

7.7

METAINFERENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

7.8

MOVINGRESTRAINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

7.9

PBMETAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

7.10 RESTRAINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

7.11 UPPER_WALLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

7.12 RESTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Command Line Tools

357

8.1

driver-float . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

8.2

driver

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

8.2.1

READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

8.3

gentemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

8.4

info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

8.5

kt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

8.6

manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

8.7

simplemd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

8.8

sum_hills

Generated by Doxygen

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

viii

CONTENTS

Miscelaneous

369

9.1

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

9.2

Continuation lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

9.3

Using VIM syntax file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

9.4

Including other files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
9.4.1

9.5

Loading shared libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
9.5.1

9.6

LOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Debugging the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
9.6.1

9.7

INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Changing exchange patterns in replica exchange
9.7.1

. . . . . . . . . . . . . . . . . . . . . . . . . . 379

RANDOM_EXCHANGES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

9.8

List of modules

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

9.9

Frequently used tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
9.9.1

histogrambead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

9.9.2

kernelfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

9.9.3

landmarkselection

9.9.4

pdbreader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

9.9.5

switchingfunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

9.9.6

Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

9.9.7

Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

9.9.7.1

Restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

9.9.7.2

Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

9.9.7.3

Replica suffix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

10 Performances

389

10.1 GROMACS and PLUMED with GPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
10.2 Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
10.3 Multiple time stepping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
10.3.1 EFFECTIVE_ENERGY_DRIFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
10.4 Multicolvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
10.5 Neighbour Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
10.6 OpenMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
10.7 Secondary Structure

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

10.8 Time your Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Generated by Doxygen

CONTENTS

11 Tutorials

395

11.1 Belfast tutorial: Analyzing CVs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
11.1.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
11.1.2 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
11.1.3 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

11.1.4 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
11.1.4.1 A note on units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
11.1.4.2 Introduction to the PLUMED input file . . . . . . . . . . . . . . . . . . . . . . . 397
11.1.4.3 MULTICOLVAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
11.1.4.4 Analysis of Collective Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 400
11.2 Belfast tutorial: Adaptive variables I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
11.2.1 Aim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
11.2.2 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

11.2.3 What happens when in a complex reaction? . . . . . . . . . . . . . . . . . . . . . . . . . 401
11.2.4 Path collective variables

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

11.2.5 A note on the path topology

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

11.2.6 How many frames do I need? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
11.2.7 Some tricks of the trade: the neighbors list.

. . . . . . . . . . . . . . . . . . . . . . . . . 405

11.2.8 The molecule of the day: alanine dipeptide . . . . . . . . . . . . . . . . . . . . . . . . . . 405
11.2.9 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
11.2.10 How to format my input? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
11.2.11 Fast forward: metadynamics on the path . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
11.3 Belfast tutorial: Adaptive variables II

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

11.3.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
11.3.2 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
11.3.3 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

11.3.4 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
11.3.4.1 Visualising the trajectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
11.3.4.2 Finding collective variables

. . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

11.3.4.3 Dimensionality reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Generated by Doxygen

CONTENTS

11.3.5 Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
11.3.6 Further Reading

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413

11.4 Belfast tutorial: Umbrella sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
11.4.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
11.4.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
11.4.2.1 Biased sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
11.4.2.2 Umbrella sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
11.4.2.3 Weighted histogram analysis method . . . . . . . . . . . . . . . . . . . . . . . 415
11.4.3 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
11.4.4 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

11.4.5 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
11.4.5.1 The model system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
11.4.5.2 Restrained simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
11.4.5.3 Reweighting the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
11.4.5.4 A free-energy landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
11.4.5.5 Combining multiple restraints . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
11.4.6 Comments

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

11.4.6.1 How does PLUMED work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
11.4.7 Further Reading

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

11.5 Belfast tutorial: Out of equilibrium dynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
11.5.1 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

11.5.2 Steered MD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
11.5.3 Moving on a more complex path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
11.5.4 Why work is important? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
11.5.5 Targeted MD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
11.6 Belfast tutorial: Metadynamics

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

11.6.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
11.6.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
11.6.3 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
11.6.4 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Generated by Doxygen

CONTENTS

11.6.5 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
11.6.5.1 The model system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
11.6.5.2 Exercise 1. Setup and run a metadynamics simulation . . . . . . . . . . . . . . 428
11.6.5.3 Exercise 2. Restart a metadynamics simulation . . . . . . . . . . . . . . . . . . 430
11.6.5.4 Exercise 3. Calculate free-energies and monitor convergence . . . . . . . . . . 430
11.6.5.5 Exercise 4. Setup and run a well-tempered metadynamics simulation, part I . . . 432
11.6.5.6 Exercise 5. Setup and run a well-tempered metadynamics simulation, part II

. . 433

11.7 Belfast tutorial: Replica exchange I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
11.7.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
11.7.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
11.7.3 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
11.7.4 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

11.7.5 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
11.7.5.1 The model system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
11.7.5.2 Exercise 1. Setup and run a PT simulation, part I . . . . . . . . . . . . . . . . . 435
11.7.5.3 Exercise 2. Setup and run a PT simulation, part II

. . . . . . . . . . . . . . . . 437

11.7.5.4 Exercise 3. Setup and run a PTMetaD simulation . . . . . . . . . . . . . . . . . 438
11.7.5.5 Exercise 4. The Well-Tempered Ensemble . . . . . . . . . . . . . . . . . . . . 439
11.8 Belfast tutorial: Replica exchange II and Multiple walkers

. . . . . . . . . . . . . . . . . . . . . . 441

11.8.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
11.8.1.1 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
11.8.2 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

11.8.3 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
11.8.3.1 Bias-Exchange Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
11.8.3.2 Convergence of the Simulations . . . . . . . . . . . . . . . . . . . . . . . . . . 443
11.8.3.3 Bias-Exchange Analysis with METAGUI . . . . . . . . . . . . . . . . . . . . . . 443
11.8.3.4 Multiple Walker Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
11.8.4 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
11.9 Belfast tutorial: NMR restraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
11.9.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Generated by Doxygen

xii

CONTENTS

11.9.1.1 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
11.9.2 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

11.9.3 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
11.9.3.1 Experimental data as Collective Variables . . . . . . . . . . . . . . . . . . . . . 447
11.9.3.2 Replica-Averaged Restrained Simulations . . . . . . . . . . . . . . . . . . . . . 448
11.9.4 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
11.10Belfast tutorial: Steinhardt Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
11.10.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
11.10.1.1 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
11.10.2 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

11.10.3 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
11.10.3.1 Simplemd

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

11.10.3.2 Coordination Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
11.10.3.3 Steinhard parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
11.10.3.4 Local versus Global . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
11.10.3.5 Local Steinhardt parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
11.10.4 Further Reading

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

11.11Cambridge tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
11.11.1 Alanine dipeptide: our toy model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
11.11.2 Exercise 1. Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
11.11.2.1 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
11.11.2.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
11.11.2.3 Setup, run, and analyse a well-tempered metadynamics simulation
11.11.2.4 Calculate free-energies and monitor convergence

. . . . . . . 454

. . . . . . . . . . . . . . . . 455

11.11.3 Exercise 2. Bias-Exchange Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . 456
11.11.3.1 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
11.11.3.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
11.11.3.3 Setup, run, and analyse a well-tempered bias-exchange metadynamics simulation 457
11.11.3.4 Calculate free-energies and monitor convergence

. . . . . . . . . . . . . . . . 458

11.11.4 Exercise 3. Replica-Average Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . 459
Generated by Doxygen

CONTENTS

xiii

11.11.4.1 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
11.11.4.2 Summary of theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
11.11.4.3 The system: Chignolin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
11.11.4.4 Setup, run and analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
11.12Cineca tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
11.12.1 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

11.12.2 Alanine dipeptide: our toy model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
11.12.3 Monitoring collective variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
11.12.3.1 Exercise 1: on-the-fly analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
11.12.3.2 Exercise 2: analysis with the driver tool . . . . . . . . . . . . . . . . . . . . . . 464
11.12.4 Biasing collective variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
11.12.4.1 Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
11.12.4.2 Restraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
11.12.4.3 Using multiple replicas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
11.12.4.4 Using multiple restraints with replica exchange . . . . . . . . . . . . . . . . . . 472
11.13Using Hamiltonian replica exchange with GROMACS . . . . . . . . . . . . . . . . . . . . . . . . 475
11.13.1 Generate scaled topologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
11.13.2 Run GROMACS

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476

11.14Julich tutorial: Developing CVs in plumed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
11.14.1 Aims . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
11.14.2 Learning Outcomes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
11.14.3 Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478

11.14.4 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
11.14.5 Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
11.14.5.1 Calculating a reasonably complex collective variable . . . . . . . . . . . . . . . 479
11.14.5.2 Implementing a new collective variable . . . . . . . . . . . . . . . . . . . . . . 480
11.14.6 Final thoughts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
11.15Moving from PLUMED 1 to PLUMED 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
11.15.1 New syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
11.15.2 Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
Generated by Doxygen

xiv

CONTENTS

11.15.3 Names in output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
11.15.4 Units

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

11.15.5 Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
11.16Munster tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
11.16.1 Alanine dipeptide: our toy model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
11.16.2 Monitoring collective variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
11.16.2.1 Analyze on the fly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
11.16.2.2 Analyze using the driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
11.16.2.3 Periodic boundaries and explicit water . . . . . . . . . . . . . . . . . . . . . . . 489
11.16.2.4 Other analysis tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
11.16.3 Biasing collective variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
11.16.3.1 Metadynamics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
11.16.3.2 Restraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
11.16.3.3 Moving restraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
11.16.3.4 Using multiple replicas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
11.16.3.5 Using multiple restraints with replica exchange . . . . . . . . . . . . . . . . . . 499

12 Index of Actions

503

12.1 Full list of actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503

13 Bug List

511

Bibliography

516

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 analyse 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.3.4 (git version: 95486cf ). Manual built on Travis CI for
branch v2.3.
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 analyse 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 Plumedized version that can be found here.
• PINY-MD, in its plumed branch.

Introduction

• IPHIGENIE.
• AceMD, see this link.
• OpenMM, using the openmmp-plumed plugin.
• DL_POLY4.
• VNL-ATK, see this link.
• ABIN.

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:

• amber14
• gromacs-2016-4
• gromacs-4-5-7
• gromacs-5-0-7
• gromacs-5-1-4
• lammps-6Apr13
• namd-2-8
• namd-2-9
• qespresso-5-0-2

Alternatively, one can use PLUMED as a Command Line Tools for postprocessing 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.

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

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

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 setMPIFIntercomm"
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

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

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 lamdba-dynamics or plumed XX-hrex
branch) possibly occuring 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

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 : parallelised and added weights.
• New features in MD patches (require repatch):
– New patch for Gromacs 5.0
– Gromacs 4.6.X patch updated to 4.6.7
Generated by Doxygen

2.2 Version 2.1

– 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 repatch, and that all combinations should work
correctly (new/old PLUMED with repatched/non-repatched 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 devations with align weights different from displace weights are now considerably
faster. This will affect RMSD calculations plus other variables based on RMSD.
– WHOLEMOLECULES is slighlty faster.
– COORDINATION is slighlty 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 referenceable quantities outputted by each action
– 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 (QuantumEspresso 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

Change Log

• It is possible to run "make install" from subdirectories (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 incompleted, 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 contactmaps 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

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 repatching.
• 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 availabity 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 repatched 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

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 repatching 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 normalisation of kernel functions. This affects HISTOGRAM If these actions were used with
previous versions of the code care should be taken when analysing the results.
• Fixed a bug in derivatives of kernel functions with non-diagonal covariances. This affects the derivatives
output by sum_hills
Generated by Doxygen

2.3 Version 2.2

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 previusly installed plumed is not removed. This is to avoid
data loss if prefix variable is not properly set
Generated by Doxygen

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

• 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 relevent 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

– 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 amonst those that have a magnitude
greater than some tolerance
– New way of calculating the minimum value in multicolvars (ALT_MIN). This is less succetible 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 multcolvar, 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 usefull 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

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

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

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

– 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 repatch):
– 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

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 multple 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 infrastracture, 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 parallelised 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 constructure as a componentWithDerivatives, derivatives are automaticcaly 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

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 symmetrise 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 subdirectory.
• 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 apear 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

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

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
For users:

• Fixed plumed partial_tempering to agree with GROMACS conventions for choice of dihedrals (see
#337). Should be irrelevant for the vast majority of cases.

For developers:

• Doxygen on travis-ci has been updated to 1.8.14
• make clean now correctly removes the src/lib/plumed executable.

Generated by Doxygen

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

Configuring PLUMED

The ./configure command just generates a Makefile.conf file and a sourceme.sh file. In PLUMED 2.0 these
files were pre-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

Installation

> ./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-matheval

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
> ./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 matheval libraries is in /opt/local (this is where MacPorts put it) and configure is not able to find it you can try
Generated by Doxygen

3.1 Configuring PLUMED

> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include

Notice that PLUMED will first try to link a routine from say matheval without any additional flag, and then in case
of failure will retry adding "-lmatheval" to the LIBS options. If also this does not work, the matheval library will be
disabled and some features will not be available. This procedure allows you to use libraries with custom names. So,
if your matheval library is called /opt/local/lib/libmymatheval.so you can link it with
> ./configure LDFLAGS=-L/opt/local/lib CPPFLAGS=-I/opt/local/include LIBS=-lmymatheval

In this example, the linker will directly try to link /opt/local/lib/libmymatheval.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 matheval example, it would be -lmatheval) 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=-lmatheval

will make sure that only matheval 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 Linux you might have problems using the LDFLAGS option. In particular, if makefile complaints that it
cannot link the file 'src/lib/plumed-shared', try to set correctly the runtime path by using
> ./configure LDFLAGS="-L/opt/local/lib -Wl,-rpath,/opt/local/lib" \
CPPFLAGS=-I/opt/local/include LIBS=-lmymatheval

Notice that 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.
PLUMED needs blas and lapack. These are treated slighty 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:
Generated by Doxygen

Installation

• DYNAMIC_LIB : these are the libraries needed to compile the PLUMED library (e.g. -L/path/to/matheval lmatheval 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_MATHEVAL to enable the matheval 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 only static executables you can just set this variable to a blank ("SOEXT=").

3.1.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:

• 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 unsetting 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.
Generated by Doxygen

3.2 Compiling PLUMED

3.1.2

VMD trajectory plugins

If you configure PLUMED with VMD's 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.2

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

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.
> cd regtest
> make

Notice that regtests are performed using the "plumed" executable that is currenty in the path. You can check the
exact version they will use by using the command
> which plumed

This means that if you do not source "sourceme.sh", the tests will fails. This does not mean that plumed is not
working it just means that you haven't told them shell where to find 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 hardcoded 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.

3.3

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. The standard way to do it is during the configure step:
> ./configure --prefix=$HOME/opt
> make
> make install
Generated by Doxygen

3.3 Installing PLUMED

However, you can also change it after compilation setting the variable prefix.

> ./configure
> make
> make install prefix=$HOME/opt

If you didn't specify the --prefix option during configure, and you did not set the prefix variable when installing, 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, executables are 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 amongst 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

3.4

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:

• amber14
• gromacs-2016-4
• gromacs-4-5-7
• gromacs-5-0-7
• gromacs-5-1-4
• lammps-6Apr13
• namd-2-8
• namd-2-9
• qespresso-5-0-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 executible 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 enginge (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.5 Cross compiling

• –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 it is not currently possible to link PLUMED as a static library (something like 'libplumed.a'). The reason
for this is that PLUMED heavily relies on C++ static constructors that do not behave well in static libraries. For this
reason, to produce a static executable with an MD code + PLUMED we link PLUMED as a collection of object files.

If your MD code is not supported, you may want to implement an interface for it. Refer to the developer manual
.

3.5

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

3.6

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 openmpi using
> sudo port install plumed +openmpi

Using gcc instead of native compilers is recommended so as to take advantage of openMP
> sudo port install plumed +openmpi +gcc7

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 precompiled 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 gcc compiler and openmpi:
> sudo port install plumed +openmpi +gcc7
> sudo port install gromacs-plumed +openmpi +gcc7

In case you want to combine gromacs with the unstable version of plumed, use this instead:
> sudo port install plumed-devel +openmpi +gcc7
> sudo port install gromacs-plumed +openmpi +gcc7

Notice that gromacs should be compiled using the same compiler variant as plumed (in this example +openmpi
+gcc7). 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 hardcoded. 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.7 Installing PLUMED on a cluster

3.7

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 additionaly features if specific libraries are available upon compiling it. Install libmatheval first and check if PLUMED ./configure is detecting it. Libmatheval is a must have
with PLUMED. 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.
libmatheval).
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 libmatheval, then load it while you compile PLUMED. If you provide
the following option to configure LDFLAGS="-Wl,-rpath,$LD_LIBRARY_PATH", the PLUMED executable
and library will remember where libmatheval is, without the need to load libmatheval 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

Installation

3.8

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

3.9

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.

• amber14
• gromacs-2016.4
• gromacs-4.5.7
• gromacs-5.0.7
• gromacs-5.1.4
• lammps-6Apr13
• namd-2.8
• namd-2.9
• qespresso-5.0.2

3.9.1

amber14

PLUMED can be incorporated into amber (sander module) using the standard patching procedure. Patching must
be done in the root directory of amber before compilation.
To enable PLUMED in a sander simulation one should use add to the cntrl input namelist these two fields:
plumed=1 , plumedfile='plumed.dat'
The first is switching plumed on, the second is specifying the name of the plumed input file.
This patch is compatible with the MPI version of sander and support multisander. However, replica exchange is not
supported. Multisander can thus only be used for multiple walkers metadynamics or for ensemble restraints.
For more information on amber you should visit http://ambermd.org
Generated by Doxygen

3.9 Code specific notes

3.9.2

gromacs-2016.4

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.9.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. Gromcas 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.9.4

gromacs-5.0.7

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.
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.9.5

gromacs-5.1.4

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
This patch also implements the -hrex keyword for gromacs. See Using Hamiltonian replica exchange with GROMACS
For more information on gromacs you should visit http://www.gromacs.org
Generated by Doxygen

3.9.6

Installation

lammps-6Apr13

PLUMED can be incorporated into LAMMPS using a simple patching procedure. Patching must be done before
LAMMPS is configured. After patching, one should enable PLUMED using the command make yes-user-plumed In
the same way, before reverting one should disable PLUMED using the command make no-user-plumed
Also notice that command "fix plumed" should be used in lammps input file after the relevant input parameters have
been set (e.g. after "timestep" command)
See also http://lammps.sandia.gov/doc/Section_commands.html for further info on processing
LAMMPS input, as well as this discussion on github: http://github.com/plumed/plumed2/issues/67.
For more information on LAMMPS you should visit http://lammps.sandia.gov/

3.9.7

namd-2.8

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.9.8

namd-2.9

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.9.9

qespresso-5.0.2

For more information on Quantum Espresso you should visit http://www.quantum-espresso.org

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 biassing 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 bounadry 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 commma 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:
DISTANCE ATOMS=1,2

(see DISTANCE)
Then PLUMED will do nothing other than read in your input file. In contrast if you do:
DISTANCE ATOMS=1,2 LABEL=d1
PRINT ARG=d1 FILE=colvar STRIDE=10

(see PRINT)
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:

Getting started

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 analisys 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 how to convert from
the plumed default unit into that new unit or by using the shortcuts described below. This directive MUST appear at
the BEGINNING of the plumed.dat file. The same units must be used througout 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.

Options

Generated by Doxygen

4.2 UNITS

NATURAL

( default=off ) use natural units

LENGTH

TIME

the units of lengths. Either specify a conversion factor from the default, nm, or A (for angstroms)
or um
the units of energy. Either specify a conversion factor from the default, kj/mol, or use j/mol or
kcal/mol
the units of time. Either specify a conversion factor from the default, ps, or use ns or fs

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

ENERGY

Examples

# this is using nm - kj/mol - fs
UNITS LENGTH=nm TIME=fs

If a number, x, is found, the new unit is equal to x (default units)

# this is using nm - kj/mol - fs
UNITS LENGTH=nm TIME=0.001

Generated by Doxygen

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 postions directly. Consquentially, 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 encourntered. 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
implementing having an unmanigiably large ammount 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

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,17,18,19,20
LABEL=g2
• numerical ranges with a stride. So GROUP ATOMS=10-100:10 LABEL=g3 is equivalent to GROUP ATO←MS=10,20,30,40,50,60,70,80,90,100 LABEL=g3
• atoms ranges with a negative stride. So GROUP ATOMS=100-10:-10 LABEL=g4 is equivalent to GROUP
ATOMS=100,90,80,70,60,50,40,30,20,10 LABEL=g4
• all the above methods together. For example GROUP ATOMS=1,2,10-20,40-60:5,100-70:-2 LABEL=g5.

Some collective variable must accept a fixed number of atoms, for example a DISTANCE is calculated using two
atoms only, an ANGLE is calcuated 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

5.1.1.2

This command is used to provide information on the molecules that are present in your system.

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 probem - 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.

WHOLEMOLECULES ENTITY0=1-100
e2e: DISTANCE ATOMS=1,100 NOPBC
RESTRAINT ARG=e2e KAPPA=1 AT=5
Generated by Doxygen

5.1 Groups and Virtual Atoms

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.

# 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 coordinatesin the
local reference frame formed by three atoms.The computed ghost atom is
stored as a virtual atom that can be accessed inan atom list through the the
label for the GHOST action that creates it.

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:

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

Generated by Doxygen

Collective variables

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 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 take the ordered list of atoms from the ATOMS keyword.
• If NDX_FILE is present append the list from the the gromacs group.
• If REMOVE is present remove the first occurence 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.
• If SORT is present resulting list is sorted.
• If UNIQUE is present the resuling list is sorted 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

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,13 (labeled 'h'):
Generated by Doxygen

5.1 Groups and Virtual Atoms

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

(see also COORDINATION and PRINT)
Groups can be conveniently stored in a separate file. E.g. one could create a file named 'groups.dat' which reads

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

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

(see also INCLUDE, COORDINATION, and PRINT). 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

# 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

(see also DUMPATOMS)
A list can be edited with REMOVE

# take one atom every three
ox: GROUP ATOMS=1-90:3
# take the remaining atoms
hy: GROUP ATOMS=1-90 REMOVE=ox
DUMPATOMS ATOMS=ox FILE=ox.gro
DUMPATOMS ATOMS=hy FILE=hy.gro

(see also DUMPATOMS)

5.1.4

MOLINFO
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
Generated by Doxygen

Collective variables

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 whenenver 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 keyoword.
Using MOLINFO with a protein's or nucleic acid's pdb extends the possibility of atoms selection using the @ special
symbol in the form

@"definition"-chainresiduenum
@"definition"-residuenum

So for example

@psi-1 will select the atoms defining the psi torsion of residue 1
@psi-C1 will define the same torsion for residue 1 of chain C.

In the following are listed the current available definitions:
For protein residues, the following groups are available:

@phi-#
@psi-#
@omega-#
@chi1-#

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-#
Generated by Doxygen

5.1 Groups and Virtual Atoms

# 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-chainresiduenum or

@atom-residuenum.
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.

MOLINFO STRUCTURE=reference.pdb
ALPHARMSD RESIDUES=all TYPE=DRMSD LESS_THAN={RATIONAL R_0=0.08 NN=8 MM=12} LABEL=a
Generated by Doxygen

Collective variables

(see also ALPHARMSD)
The following example prints the distance corresponding to the hydrogen bonds in a GC Watson-Crick pair.

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

(see also DISTANCE).
This example use MOLINFO to calculate torsions angles

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
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 consecute atoms (1-100), but it is
also possible to skip some atoms, provided consecute chosen atoms are close enough.
The atoms involved can be specified using

Generated by Doxygen

5.1 Groups and Virtual Atoms

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

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

MOLTYPE

the type of molecule that is under study. This is used to define the backbone atoms

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.
# 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

(see also DUMPATOMS)
This command instructs plumed to reconstruct two molecules containing atoms 1-20 and 30-40
WHOLEMOLECULES ENTITY0=1-20 ENTITY1=30-40
DUMPATOMS FILE=dump.xyz ATOMS=1-20,30-40

(see also DUMPATOMS)
This command instructs plumed to reconstruct the chain of backbone atoms in a protein
MOLINFO STRUCTURE=helix.pdb
WHOLEMOLECULES RESIDUES=all MOLTYPE=protein

(See also MOLINFO)

5.1.6

FIT_TO_TEMPLATE

Generated by Doxygen

Collective variables

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 correclty 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.
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.

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.

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.

Examples

Align the atomic position to a template then print them
# to see the effect, one could dump the atoms before alignment
DUMPATOMS FILE=dump-before.xyz ATOMS=1-20
FIT_TO_TEMPLATE STRIDE=1 REFERENCE=ref.pdb TYPE=SIMPLE
DUMPATOMS FILE=dump-after.xyz ATOMS=1-20

(see also DUMPATOMS)

5.1.7

WRAPAROUND

Generated by Doxygen

5.1 Groups and Virtual Atoms

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:

• 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 analyse 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.
Generated by Doxygen

Collective variables

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

(see also WHOLEMOLECULES, GROUP and DUMPATOMS)
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:
# 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

(see also TORSION, GROUP, WHOLEMOLECULES and DUMPATOMS)
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.
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

(see also GROUP COM DUMPATOMS)
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 oxygens will be brought close to the solute, and all the hydrogens
will be kept close to their related oxygen.
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

(see also GROUP COM DUMPATOMS)
Generated by Doxygen

5.1 Groups and Virtual Atoms

5.1.8

RESET_CELL

Generated by Doxygen

Collective variables

This is part of the generic module

This action is used to rotate the full cell
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

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

(see also DUMPATOMS)

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.
Generated by Doxygen

5.1 Groups and Virtual Atoms

This action calculates the position of a new virtual atom using the following formula:

P
wi fi sin (2πxi,α )
1
i
xα =
arctan P
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.

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 recognise 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 recognise 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:
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 calclates 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:
Generated by Doxygen

Collective variables

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 coordinations 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
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 PBCs 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.

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

WEIGHTS

Center is computed as a weighted average.

Examples

# 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
Generated by Doxygen

5.1 Groups and Virtual Atoms

# this is another way of stating the same:
c1bis: CENTER ATOMS=1,10 WEIGHTS=2,1
# center of mass among these atoms:
c2: CENTER ATOMS=2,3,4,5 MASS
d1: DISTANCE ATOMS=c1,c2
PRINT ARG=d1

(See also DISTANCE, COM and PRINT).

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 PBCs 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.

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

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:
COM ATOMS=1-7
Generated by Doxygen

LABEL=c1

Collective variables

COM ATOMS=15,20
DISTANCE ATOMS=c1,c2
PRINT ARG=d1

LABEL=c2
LABEL=d1

(See also DISTANCE and PRINT).

5.1.12

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 coordinats (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

Generated by Doxygen

5.1 Groups and Virtual Atoms

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.

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

(See also ANGLE and RESTRAINT).
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).

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

(See also FIT_TO_TEMPLATE and DISTANCE).

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:

GHOST ATOMS=1,5,10 COORDINATES=10.0,10.0,10.0 LABEL=c1
COM ATOMS=15,20
LABEL=c2
DISTANCE ATOMS=c1,c2 LABEL=d1
PRINT ARG=d1

(See also DISTANCE and PRINT).
Generated by Doxygen

5.2

Collective variables

CV Documentation

The following list contains descriptions of a number of the colvars that are currently implemented in PLUMED.

Generated by Doxygen

5.2 CV Documentation

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.

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 quantitieswith or without derivatives.

CONTACTMAP

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 distancebetween two contact maps. Each distance can also be weighted for a given
value. CONTACTMAP can be used togetherwith FUNCPATHMSD to define
a path in the contactmap space.

COORDINATION
CS2BACKBONE

Calculate coordination numbers.
This collective variable calculates the backbone chemical shifts for a protein.

DHENERGY

Calculate Debye-Huckel interaction energy among GROUPA and GROUPB.

DIHCOR

Measures the degree of similarity between dihedral angles.

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.

ENERGY

Calculate the total energy of the simulation box.

ERMSD

Calculate eRMSD with respect to a reference structure.

FAKE

This is a fake colvar container used by cltools or various other actionsand
just support input and period definition

FRET

Calculate the FRET efficiency between a pair of atoms.The efficiency is calculated using the Forster relation:

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.

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 atomsor ambiguous NOE.

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.

PRE

PROPERTYMAP

Calculates the Paramegnetic Resonance Enhancement intensity ratio between two atoms.The reference atom for the spin label is added with SPI←NLABEL, the affected atom(s)are give as numbered GROUPA1, GROUPA2,
...The additional parameters needed for the calculation are given as INEPT,
the inepttime, TAUC the correlation time, OMEGA, the larmor frequency and
RTWO for the relaxationtime.
Calculate generic property maps.

PUCKERING

Calculate sugar pseudorotation coordinates.

RDC

Calculates the (Residual) Dipolar Coupling between two atoms.

TEMPLATE

This file provides a template for if you want to introduce a new CV.

TORSION

Calculate a torsional angle.

Generated by Doxygen

Collective variables

VOLUME

5.2.1

Calculate the volume of the simulation box.

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.

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.

The atoms involved can be specified using

ATOMS

the atoms involved in each of the collective variables you wish to calculate. Keywords like ATOM←S1, ATOMS2, ATOMS3,... should be listed and one CV will be calculated for each ATOM keyword
you specify (all ATOM keywords should define the same number of 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...

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 torsions 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 parallelize

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

Examples

The following provides an example of the input for an alpha beta similarity.

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

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 torsions 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:

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 4th residue of the protein.

5.2.2

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 interatomic distances in the reference and instantaneous structures.
This colvar is based on the following reference [4]. 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:
Generated by Doxygen

Collective variables

X 1−

ri −d0
r0

1−

ri −d0
r0

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 [4]. The R_0 parameter must be set by the user - the value used in [4] 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
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 anthing 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 idealised
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 referened 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 are customizable. In particular, by using the LABEL keyword in the description of you LESS_THAN
function you can set name of the component that you are calculating
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 quantitities 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 quantitities 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.
Generated by Doxygen

5.2 CV Documentation

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.
The r_0 parameter of the switching function.

D_0

( default=0.0 ) The d_0 parameter of the switching function

( default=8 ) The n parameter of the switching function

( default=12 ) The m parameter of the switching function

Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

VERBOSE

( default=off ) write a more detailed output

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

LESS_THAN

MIN

ALT_MIN

min

log

exp

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.
MOLINFO STRUCTURE=helix.pdb
ALPHARMSD RESIDUES=all TYPE=DRMSD LESS_THAN={RATIONAL R_0=0.08 NN=8 MM=12} LABEL=a
Generated by Doxygen

Collective variables

(see also MOLINFO)

5.2.3

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 i-th 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.
Generated by Doxygen

5.2 CV Documentation

a: ANGLE ATOMS=1,2,3
# equivalently one could state:
# a: ANGLE ATOMS=1,2,2,3
b: ANGLE ATOMS=1,2,3,4
PRINT ARG=a FILE=COLVAR1
PRINT ARG=b FILE=COLVAR2

(see also PRINT)

5.2.4

ANTIBETARMSD
This is part of the secondarystructure module

Probe the antiparallel beta sheet content of your protein structure.
Two protein segments containing three continguous 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 interatomic distances in the reference and instantaneous structures.
This colvar is based on the following reference [4]. 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 resemebles
an anti paralel beta sheet. This is done by calculating the following sum of functions of the rmsd distances:

X 1−

ri −d0
r0

1−

ri −d0
r0

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 [4]. The R_0 parameter must be set by the user - the value used in [4] 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 anthing other than TYPE=DRMSD. For more details as to how to do this see
WHOLEMOLECULES.
Description of components

Generated by Doxygen

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 quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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

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.
The r_0 parameter of the switching function.

D_0

( default=0.0 ) The d_0 parameter of the switching function

( default=8 ) The n parameter of the switching function

( 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

VERBOSE

( default=off ) write a more detailed output

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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

min

ALT_MIN

log

exp

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.

MOLINFO STRUCTURE=helix.pdb
ANTIBETARMSD RESIDUES=all TYPE=DRMSD LESS_THAN={RATIONAL R_0=0.08 NN=8 MM=12} LABEL=a

(see also MOLINFO)

5.2.5

CELL
This is part of the colvar module

Calculate the components of the simulation cell

Description of components

Generated by Doxygen

Collective variables

By default this Action calculates the following quantities. These quanties 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

5.2 CV Documentation

Quantity

Description

the ax component of the cell matrix

the ay component of the cell matrix

the az component of the cell matrix

the bx component of the cell matrix

the by component of the cell matrix

the bz component of the cell matrix

the cx component of the cell matrix

the cy component of the cell matrix

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

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

(See also COMBINE and PRINT).

5.2.6

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 these customizable components the following quantities will always be output

Generated by Doxygen

Quantity

Description

the # value

Collective variables

Compulsory keywords

VALUES

( default=NAN ) The values of the constants

VALUE

( default=NAN ) The value of the constant

Options

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

NODE←RIV

( default=off ) Set to TRUE if you want values without derivatives.

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

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

(See also DISTANCE, SORT, and PRINT).
In case you want to pass a single value you can use VALUE:

cn: CONSTANT VALUE=1.0
dis: DISTANCE ATOMS=1
sss: SORT ARG=cn,dis
PRINT ARG=sss.1

5.2.7

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

5.2 CV Documentation

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 quanties 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
contant 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

Collective variables

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 SWITH), while R_0 is the contact distance. WEIGHT gives the relative weight of each contact to the final
distance measure.

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 [5]

# 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 PRINT and switchingfunction)

5.2.8

COORDINATION
This is part of the colvar module

Calculate coordination numbers.
This keyword can be used to calculate the number of contacts between two groups of atoms and is defined as

sij

i∈A i∈B
Generated by Doxygen

5.2 CV Documentation

where sij is 1 if the contact between atoms i and j is formed, zero otherwise. In practise, 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

( default=6 ) The n parameter of the switching function

( 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 neighbour list to speed up the calculation

NL_CUTOFF

The cutoff for the neighbour list

NL_STRIDE

The frequency with which we are updating the atoms in the neighbour list

Generated by Doxygen

Collective variables

SWITCH

This keyword is used if you want to employ an alternative to the continuous
swiching 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 neighbour list is used to make this calculation
faster, this neighbour list is updated every 100 steps.

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.

c: COORDINATION GROUPA=1 GROUPB=1 R_0=0.3
PRINT ARG=c STRIDE=10

c1: COORDINATION GROUPA=1-10 GROUPB=1-10 R_0=0.3
x: COORDINATION GROUPA=1-10 R_0=0.3
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. Notice that to get the same result you
# should double it
PRINT ARG=c1,c2 STRIDE=10

See also PRINT and COMBINE

5.2.9

CS2BACKBONE
This is part of the colvar module

This collective variable calculates the backbone chemical shifts for a protein.
The functional form is that of CamShift [6]. The chemical shifts of the selected nuclei/residues are saved as components. Reference experimental values can also be stored as components. The two components can then be used
to calculate either a scoring function as in [7] [8], using the keyword CAMSHIFT or to calculate ensemble averages
chemical shift per chemical shift as in [9] [10] (see STATS and ENSEMBLE).
CamShift calculation is relatively heavy because it often uses a large number of atoms, in order to make it faster it
is currently parallelised with OpenMP.
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.
In general the system for which chemical shifts are calculated must be completly included in ATOMS and a TEMP←LATE pdb file for the same atoms should be provided as well in the folder DATA. The atoms are made automatically
Generated by Doxygen

5.2 CV Documentation

whole unless NOPBC is used, in particular if the system is made of by multiple chains it is usually better to use
NOPBC and make the molecule whole WHOLEMOLECULES selecting an appropriate order.
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), all the six files should always be
present. 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 go from 1 to N irrespectively of the
numbers used in the pdb file. The first and last residue of each chain should be preceeded by a # character. Termini
groups like ACE or NME should be removed from the PDB.

CAshifts.dat:
#1 0.0
2 55.5
3 58.4
.
.
#last 0.0
#last+1 (first) of second chain
.
#last of second chain

The default behaviour 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
backcalculated values.
A pdb file is needed to the generate a simple topology of the protein. For histidines 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.
One more standard file is also needed in the folder DATA: camshift.db. This file includes all the CamShift parameters
and can be found in regtest/basic/rt45/data/ .
All the above files must be in a single folder that must be specified with the keyword DATA.
Additional material and examples can be also found in the tutorial Belfast tutorial: NMR restraints

Description of components

Generated by Doxygen

Quantity

Description

the calculated Ha hydrogen chemical shifts

the calculated H hydrogen chemical shifts

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

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

Collective variables

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

DATA

( default=data/ ) The folder with the experimental chemical shifts.

TEMPLATE

( default=template.pdb ) A PDB file of the protein system to initialise ALMOST.

NEIGH_FREQ

( default=20 ) Period in step for neighbour list update.

NRES

Number of residues, corresponding to the number of chemical shifts.

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 ) Set to TRUE if you to calculate a single CamShift score.

CAMSHIFT
NOEXP

( default=off ) Set to TRUE if you don't want to have fixed components with the
experimetnal values.

Examples

In this first example the chemical shifts are used to calculate a scoring function to be used in NMR driven Metadynamics [8] :
whole: GROUP ATOMS=2612-2514:-1,961-1:-1,2466-962:-1,2513-2467:-1
WHOLEMOLECULES ENTITY0=whole
cs: CS2BACKBONE ATOMS=1-2612 NRES=176 DATA=../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 [9] [10].
cs: CS2BACKBONE ATOMS=1-174 DATA=data/ NRES=13
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

(See also WHOLEMOLECULES, STATS, METAD, RESTRAINT and PRINT)

5.2.10

DHENERGY

Generated by Doxygen

5.2 CV Documentation

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

e−κ|rij |
1 XX
qi qj
4πr 0
|rij |
i∈A j∈B

This collective variable can be used to analyze or induce electrostatically driven reactions [11]. Notice that the value
of the DHENERGY is returned in plumed units (see UNITS).
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

( 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 neighbour list to speed up the calculation

NL_CUTOFF

The cutoff for the neighbour list

NL_STRIDE

The frequency with which we are updating the atoms in the neighbour list

Generated by Doxygen

Collective variables

Examples

# 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

(see also PRINT)

5.2.11

DIHCOR
This is part of the multicolvar module

Measures the degree of similarity between dihedral angles.
This colvar calculates the following quantity.

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

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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

Examples

Generated by Doxygen

5.2 CV Documentation

The following provides an example input for the dihcor action

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 correation 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 betwene 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 torsions 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:

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

5.2.12

DIPOLE
This is part of the colvar module

Calculate the dipole moment for a group of atoms.

Description of components

Keyword

Description

COMPONENTS

the x-component of the dipole

COMPONENTS

the y-component of the dipole

COMPONENTS

the z-component of the dipole

The atoms involved can be specified using

Generated by Doxygen

Collective variables

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

Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

COMPONENTS

( default=off ) calculate the x, y and z components of the dipole separately and
store them as label.x, label.y and label.z

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

d: DIPOLE GROUP=1-10
PRINT FILE=output STRIDE=5 ARG=5

(see also PRINT)

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.13

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:
Generated by Doxygen

5.2 CV Documentation

p(x0 , y 0 , z 0 ) = ρ

where ρ is some target density. This action caculates the distance projected on the x, y or z axis between the
position of some test particle and this surface of constant field density.

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 esimtation

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

the value we would like for the contour

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 parallelize

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 concentraed along some part of the z axis so that you an interface
between a liquid/solid and the vapour. 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.
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

5.2.14

DISTANCE

Generated by Doxygen

Collective variables

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

Keyword

Description

COMPONENTS

the x-component of the vector connecting the two atoms

COMPONENTS

the y-component of the vector connecting the two atoms

COMPONENTS

the z-component of the vector connecting the two atoms

SCALED_COMPONENTS

the normalized projection on the first lattice vector of the vector connecting the two atoms

SCALED_COMPONENTS

the normalized projection on the second lattice vector of the vector
connecting the two atoms

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

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.
d1: DISTANCE ATOMS=3,5
d2: DISTANCE ATOMS=2,4
d2c: DISTANCE ATOMS=2,4 COMPONENTS
PRINT ARG=d1,d2,d2c.x

(See also PRINT).
The following input computes the end-to-end distance for a polymer of 100 atoms and keeps it at a value around 5.
WHOLEMOLECULES ENTITY0=1-100
e2e: DISTANCE ATOMS=1,100 NOPBC
RESTRAINT ARG=e2e KAPPA=1 AT=5

(See also WHOLEMOLECULES and RESTRAINT).
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
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
# 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

(see also COM, COMBINE, and METAD)
Using SCALED_COMPONENTS this problem should not arise because they are always periodic with domain (-0.←5,+0.5).

5.2.15

ENERGY

Generated by Doxygen

Collective variables

This is part of the colvar module

Calculate the total energy of the simulation box.
Total energy can be biased with umbrella sampling [12] or with well tempered metadynamics [13].
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

ENERGY LABEL=ene
PRINT ARG=ene

(See also PRINT).

5.2.16

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:

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 ~
weghting 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(
γ
Generated by Doxygen

5.2 CV Documentation

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 [14]
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

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.

Generated by Doxygen

Collective variables

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.

MOLINFO STRUCTURE=reference.pdb
eRMSD1: ERMSD REFERENCE=reference.pdb ATOMS=@lcs-1,@lcs-2,@lcs-3,@lcs-4,@lcs-5,@lcs-6

5.2.17

FAKE
This is part of the colvar module

This is a fake colvar container used by cltools or various other actions and just support input and period definition

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 componnets that this variable is supposed to have. Periodicity is
ruled by PERIODIC keyword

Examples

FAKE ATOMS=1 PERIODIC=-3.14,3.14

LABEL=d2

(See also PRINT).
Generated by Doxygen

5.2 CV Documentation

5.2.18

FRET
This is part of the colvar module

Calculate the FRET efficiency between a pair of atoms. The efficiency is calculated using the Forster relation:

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

Compulsory keywords

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.

fe1: FRET ATOMS=3,5 R0=5.5
fe2: FRET ATOMS=2,4 R0=5.5
PRINT ARG=fe1,fe2

(See also PRINT).
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.
Generated by Doxygen

Collective variables

WHOLEMOLECULES ENTITY0=1-100
fe: FRET ATOMS=1,100 R0=5.5 NOPBC
RESTRAINT ARG=fe KAPPA=100 AT=0.5

(See also WHOLEMOLECULES and RESTRAINT).
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

5.2.19

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 [15]. 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))
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 ammount by which a set of collective variables change. As
such this implementation of the propertymap 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

the value of the lambda parameter for paths

Options

Generated by Doxygen

5.2 CV Documentation

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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.

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
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.20

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.171
-1.819
-1.177
-1.313
-1.845
-0.003
0.205
0.009
1.121
1.723
1.423
0.873
2.477

0.295
-0.143
-0.889
0.341
0.961
-0.019
-1.051
0.135
0.799
1.669
0.519
-0.161
1.187

2.045
1.679
2.401
0.529
-0.011
0.021
0.259
-1.509
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
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

GYRATION

Generated by Doxygen

Collective variables

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 [16]
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:

Pn
i ri mi
rCOM = 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 PBCs 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.

The atoms involved can be specified using

ATOMS

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

Generated by Doxygen

5.2 CV Documentation

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.

GYRATION TYPE=RADIUS ATOMS=10-20 LABEL=rg
PRINT ARG=rg STRIDE=1 FILE=colvar

(See also PRINT)

5.2.21

JCOUPLING
This is part of the colvar module

Calculates 3 J coupling constants for a dihedral angle.
The J-coupling between two atoms is given by the Karplus relation:

J(θ) = A cos2 (θ + ∆θ) + B cos(θ + ∆θ) + C

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
Description of components

Generated by Doxygen

Collective variables

Quantity

Description

the calculated J-coupling

In addition the following quantities can be calculated by employing the keywords listed below
Quantity

Keyword

Description

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...

Compulsory keywords

TYPE

Type of J-coupling to compute (HAN,HAHN,CCG,NCG,CUSTOM)

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 ) Set this flag if you want to have fixed components with the experimental values.

ADDCOUPLINGS

Karplus parameter A

Karplus parameter B

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 datapoints and compute the correlation and other measures and
finally print the results.

MOLINFO MOLTYPE=protein STRUCTURE=peptide.pdb
Generated by Doxygen

5.2 CV Documentation

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
ENDPLUMED

(See also PRINT, STATS)

5.2.22

NOE
This is part of the colvar 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.

N OE() = (

Neq
1 X 1 −1
( )) 6
Neq j rj6

Intensities can then in principle ensemble averaged using ENSEMBLE and used to calculate a scoring function for
example with METAINFERENCE.

Description of components

Description

noe

the # NOE

In addition the following quantities can be calculated by employing the keywords listed below

Generated by Doxygen

Quantity

Keyword

Description

exp

ADDEXP

the # NOE experimental distance

Collective variables

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...

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 ) Set to TRUE if you want to have fixed components with the experimental reference values.

ADDEXP

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 1-2 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.

NOE ...
GROUPA1=1,3 GROUPB1=2,2
GROUPA2=5 GROUPB2=7
GROUPA3=4,4,8,8 GROUPB3=15,16,15,16
LABEL=noes
... NOE
PRINT ARG=noes.* FILE=colvar

(See also PRINT)

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 continguous 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
Generated by Doxygen

5.2 CV Documentation

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 interatomic distances in the reference and instantaneous structures.
This colvar is based on the following reference [4]. 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:

X 1−

ri −d0
r0

1−

ri −d0
r0

n
m

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 [4]. The R_0 parameter must be set by the user - the value used in [4] 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 anthing other than TYPE=DRMSD. For more details as to how to do this see
WHOLEMOLECULES.
Description of components

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 quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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

Generated by Doxygen

100

Collective variables

RESIDUES

Compulsory keywords

TYPE

R_0

D_0

( default=0.0 ) The d_0 parameter of the switching function

( default=8 ) The n parameter of the switching function

( 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

VERBOSE

( default=off ) write a more detailed output

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

LESS_THAN

MIN

ALT_MIN

min

log

exp

min

Generated by Doxygen

5.2 CV Documentation

101

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

Examples

The following input calculates the number of six residue segments of protein that are in an parallel beta sheet
configuration.

MOLINFO STRUCTURE=helix.pdb
PARABETARMSD RESIDUES=all TYPE=DRMSD LESS_THAN={RATIONAL R_0=0.08 NN=8 MM=12} LABEL=a

(see also MOLINFO)

5.2.24

PATHMSD
This is part of the colvar module

This Colvar calculates path collective variables.
This is the Path Collective Variables implementation ( see [17] ). 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).

Description of components

Description

sss

the position on the path

zzz

the distance from the path

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

Generated by Doxygen

102

Collective variables

Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

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

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
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 [17] 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 = 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 ].
Generated by Doxygen

5.2 CV Documentation

103

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 ammount 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.

Compulsory keywords

REFERENCE

a pdb file containing the set of reference configurations

TYPE

LAMBDA

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 parallelize

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

Examples

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.

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:

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:
Generated by Doxygen

104

Collective variables

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 instaneous 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
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 =

Aik (Xk − Xkref )

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 explicitally 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.
Generated by Doxygen

5.2 CV Documentation

105

Description of components

Generated by Doxygen

106

Collective variables

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

Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

NORMALIZE

( default=off ) calculate the length of the eigenvector input and divide the components by it so as to have a normalised vector

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.
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 refered 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

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

Generated by Doxygen

5.2 CV Documentation

107

Alternatively, the second configuration can specify the components of A explicitally. 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

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

108

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

Description

the x-component of the atom position

the y-component of the atom position

the z-component of the atom position

In addition the following quantities can be calculated by employing the keywords listed below
Quantity

Keyword

Description

SCALED_COMPONENTS

the normalized projection on the first lattice vector of the atom position

SCALED_COMPONENTS

the normalized projection on the second lattice vector of the atom
position

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

# align to a template
Generated by Doxygen

5.2 CV Documentation

109

FIT_TO_TEMPLATE REFERENCE=ref.pdb
p: POSITION ATOM=3
PRINT ARG=p.x,p.y,p.z

(see also FIT_TO_TEMPLATE)

5.2.28

PRE
This is part of the colvar module

Calculates the Paramegnetic Resonance Enhancement intensity ratio between two atoms. The reference atom for
the spin label is added with SPINLABEL, the affected atom(s) are give as numbered GROUPA1, 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.

Description of components

Description

pre

the # PRE

In addition the following quantities can be calculated by employing the keywords listed below
Quantity

Keyword

Description

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

Generated by Doxygen

INEPT

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).

110

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 ) Set to TRUE if you want to have fixed components with the experimetnal values.

ADDEXP

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...

PREINT

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 oxigen of the spin label
and the backbone hydrogens. Omega is the NMR frequency, RTWO the R2 for the hydrogens, INEPT of 8 ms for
the experiment and a TAUC of 1.21 ns

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

5.2.29

PROPERTYMAP
This is part of the colvar module

Calculate generic property maps.
This Colvar calculates the property maps according to the work of Spiwok [15].
Basically it calculates

P
i Xi ∗ exp(−λDi (x))
P
exp(−λDi (x))
P i
i Yi ∗ exp(−λDi (x))
Y = P
i exp(−λDi (x))
···
X
1
zzz = − log(
exp(−λDi (x)))
λ
i
X=

(5.1)
(5.2)
(5.3)
(5.4)

Generated by Doxygen

5.2 CV Documentation

111

where the parameters Xi and Yi are provided in the input pdb (allv.pdb in this case) and Di (x) is the MSD after
optimal alignment calculated on the pdb frames you input (see Kearsley).

Description of components

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

Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

NEIGH_SIZE

size of the neighbor list

NEIGH_STRIDE

how often the neighbor list needs to be calculated in time units

Examples

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 neighborlist parameter (optional but recommended for
performance) and states that the neighbor list will be calculated every 4 timesteps 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

Generated by Doxygen

ALA
ALA

1
1

-3.171
-1.819

0.295
-0.143

2.045
1.679

1.00
1.00

ALA
ALA

1
1

-3.175
-1.814

0.365
-0.106

2.024
1.685

1.00
1.00

112

Collective variables

Note
The implementation of this collective variable and of PATHMSD is shared, as well as most input options.

5.2.30

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
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 [18] . 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 [18] . 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 [19] as also discussed in [20] . 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 implentation are to be published (paper in preparation).
Components of this action are:

Description of components

Description

phs

Pseudorotation phase (5 membered rings)

amp

Pseudorotation amplitude (5 membered rings)

Pseudorotation x cartesian component (5 membered rings)

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)

Cartesian component x (6 membered rings)

Cartesian component y (6 membered rings)

Cartesian component z (6 membered rings)

The atoms involved can be specified using

Generated by Doxygen

5.2 CV Documentation

ATOMS

113

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

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.

MOLINFO STRUCTURE=rna.pdb MOLTYPE=rna
PUCKERING ATOMS=@sugar-3 LABEL=puck
PRINT ARG=puck.phs FILE=COLVAR

5.2.31

RDC
This is part of the colvar module

Calculates the (Residual) Dipolar Coupling between two atoms.
The RDC between two atomic nuclei depends on the θ angle between the inter-nuclear vector and the external
magnetic field. In isotropic media RDCs average to zero because of the orientational averaging, but when the
rotational symmetry is broken, either through the introduction of an alignment medium or for molecules with highly
anisotropic paramagnetic susceptibility, RDCs become measurable.

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
• NH -72.5388
Generated by Doxygen

114

Collective variables

• CH 179.9319
• CN -18.2385
• CC 45.2404

This collective variable calculates the Residual Dipolar Coupling for a set of couple of atoms using the above
definition. From the calculated RDCs and a set of experimental values it calculates either their correlation or the
squared quality factor

Q =

− Diexp )2
exp 2
i (Di )

(Di
iP

RDCs report only on the fraction of molecules that is aligned, this means that comparing the RDCs from a single
structure in a MD simulation to the experimental values is not particularly meaningfull, from this point of view it is
better to compare their correlation. The fraction of aligned molecules can be obtained by maximising the correlation
between the calculated and the experimental RDCs. This fraction can be used as a scaling factor in the calculation
of the RDCs in order to compare their values. The averaging of the RDCs calculated with the above definition from
a standard MD should result to 0 because of the rotational diffusion, but this variable can be used to break the
rotational symmetry.
RDCs 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 restrained simulations can be performed with this CV and the function ENSEMBLE.
Additional material and examples can be also found in the tutorial Belfast tutorial: NMR restraints

Description of components

Description

rdc

the calculated # RDC

In addition the following quantities can be calculated by employing the keywords listed below
Quantity

Keyword

Description

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...

Generated by Doxygen

5.2 CV Documentation

115

Compulsory keywords

GYROM

Add the product of the gyromagnetic constants for the bond.

SCALE

Add the scaling factor to take into account concentration and other effects.

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 ) Set to TRUE if you want to backcalculate 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 experimetnal values.

COUPLING

Add an experimental value for each coupling (needed by SVD and usefull for
ef 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 their correlation with respect to a set of experimental data
is calculated and restrained. In addition, and only for analysis purposes, the same RDCs are calculated using a
Single Value Decomposition algorithm.
RDC ...
GYROM=-72.5388
SCALE=1.0
ATOMS1=20,21
ATOMS2=37,38
ATOMS3=56,57
ATOMS4=76,77
ATOMS5=92,93
LABEL=nh
... RDC
STATS ARG=nh.* PARAMETERS=8.17,-8.271,-10.489,-9.871,-9.152
rdce: RESTRAINT ARG=nh.corr KAPPA=0. SLOPE=-25000.0 AT=1.
RDC ...
GYROM=-72.5388
SCALE=1.0
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
PRINT ARG=nh.corr,rdce.bias FILE=colvar
PRINT ARG=svd.* FILE=svd

(See also PRINT, RESTRAINT)
Generated by Doxygen

116

Collective variables

5.2.32

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

Examples

# This should be a sample input.
t: TEMPLATE ATOMS=1,2
PRINT ARG=t STRIDE=100 FILE=COLVAR

(see also PRINT)

5.2.33

TORSION
This is part of the colvar module

Generated by Doxygen

5.2 CV Documentation

117

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.
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.
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.2.34

VOLUME

Generated by Doxygen

118

Collective variables

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

Examples

The following input tells plumed to print the volume of the system

VOLUME LABEL=vol
PRINT ARG=vol

(See also PRINT).

5.3

Distances from reference configurations

One colvar that has been shown to be very sucessful 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 instantanous 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 practise 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 ammount by which a large number of collective variables change in
moving from the reference to the instaneous configurations. One could even combine RMSD distances with the
ammount 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 [21] and [22] ) 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 someset of collective variables.
Generated by Doxygen

5.3 Distances from reference configurations

119

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.
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:

d(X , X ) =

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

Generated by Doxygen

120

Collective variables

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.

DRMSD REFERENCE=file.pdb LOWER_CUTOFF=0.1 UPPER_CUTOFF=0.8

The following tells plumed to calculate a DRMSD value for a pair of molecules.

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

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

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 ) =

wi |Xi − Xi0 |2

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.
Generated by Doxygen

5.3 Distances from reference configurations

121

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

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

DIA
DIA
DIA
DIA
DIA
DIA
DIA
DIA

H
O
H
H
C
H
H
H

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

SQUARED

( default=off ) This should be setted if you want MSD instead of RMSD

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 Kearseley algorithm for each of the domains.

MULTI-RMSD REFERENCE=file.pdb TYPE=MULTI-OPTIMAL

The following tells plumed to calculate the RMSD distance btween 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.

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:
Generated by Doxygen

122

Collective variables

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
ATOM
9 CAY ALA
ATOM
10 HY1 ALA
TER
ATOM
12 HY3 ALA
ATOM
14 OY ALA
ATOM
16 HN ALA
ATOM
18 HA ALA
ATOM
19 CB ALA
ATOM
20 HB1 ALA
ATOM
21 HB2 ALA
ATOM
22 HB3 ALA
END

5.3.3

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

DIA
DIA
DIA
DIA
DIA
DIA
DIA

O
H
H
H
H
C
H

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

DIA
DIA
DIA
DIA
DIA
DIA
DIA
DIA

H
O
H
H
C
H
H
H

PCARMSD
This is part of the colvar module

Calculate the PCA components ( see [21] and [22] ) 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

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
MSD 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.
Generated by Doxygen

5.3 Distances from reference configurations

123

Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SQUARED-ROOT

( default=off ) This should be setted if you want RMSD instead of MSD

Examples

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 ) 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
Generated by Doxygen

124

Collective variables

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 1st, 4th, 6th and 28th atoms in the
MD codes input file then the indices of the corresponding refernece 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 centre
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 correclty
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
w
j
j
α
i
β

where M (X, X 0 , w0 ) is the optimal alignment matrix which is calculated using the Kearsley [23] algorithm. Again
different sets of weights are used for the alignment ( w0 ) and for the displacement calcuations ( 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.

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

5.3 Distances from reference configurations

125

Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

SQUARED

( default=off ) This should be setted if you want MSD instead of RMSD

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 Kearseley algorithm is used so this is done optimally.

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 instaneous 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

126

Collective variables

where σi is a vector of weights. Lastly, by using the METRIC=MAHALONOBIS we can compute mahalonobis
distances using:

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 containg 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 instaneous 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.

d1: DISTANCE ATOMS=1,2
d2: DISTANCE ATOMS=3,4
t1: TARGET REFERENCE=myref.pdb TYPE=EUCLIDEAN
PRINT ARG=t1 FILE=colvar

The contents of the file containing the reference structure (myref.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

5.4 Functions

5.4

127

Functions

When performing biased dynamics or analysing a trajectory you may wish to analyse/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:

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.

ENSEMBLE

Calculates the replica averaging of a collective variable over multiple replicas.

FUNCPATHMSD

This function calculates path collective variables.

FUNCSUMHILLS

LOCALENSEMBLE

Calculates the average over multiple arguments.

MATHEVAL

Calculate a combination of variables using a matheval expression.

PIECEWISE

Compute a piecewise straight line through its arguments that passes througha set of
ordered control points.

SORT

This function can be used to sort colvars according to their magnitudes.

STATS

Generated by Doxygen

128

5.4.1

Collective variables

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

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 coefficents 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 proceding 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 componets 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

Generated by Doxygen

5.4 Functions

129

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.

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.

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

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

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

130

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.

dist: DISTANCE ATOMS=3,5
ens: ENSEMBLE ARG=dist
PRINT ARG=dist,ens.dist

(See also PRINT and DISTANCE).

5.4.3

FUNCPATHMSD
This is part of the function module

This function calculates path collective variables.
This is the Path Collective Variables implementation ( see [17] ). 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 MSD that are obtained by the joint use of MSD variable and SQUARED flag (see below).

Description of components

Description

the position on the path

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

131

ARG

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 alng the path
and the distance from it in p1
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:
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
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
Generated by Doxygen

132

5.4.4

Collective variables

FUNCSUMHILLS
This is part of the function module

This function is intended to be called by the command line tool sum_hills and it is meant to integrate a HILLS file
or an HILLS file interpreted as a histogram i a variety of ways. Therefore it is 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

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

ISCLTOOL

( default=on ) use via plumed commandline: 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 welltempered 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

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

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 monodimensional INTERVAL
output file for hills
Generated by Doxygen

5.4 Functions

133

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.5

LOCALENSEMBLE
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

Generated by Doxygen

134

Collective variables

Examples

The following input tells plumed to calculate the chemical shifts for four different proteins in the same simulation
box then average them, calcualated the sum of the squared deviation with respect to the experiemntal values and
applies a linear restraint.

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:
csb:
csc:
csd:

CS2BACKBONE
CS2BACKBONE
CS2BACKBONE
CS2BACKBONE

ensca:
enscb:
ensco:
enshn:
ensnh:
stca:
stcb:
stco:
sthn:
stnh:

ATOMS=chaina
ATOMS=chainb
ATOMS=chainc
ATOMS=chaind

LOCALENSEMBLE
LOCALENSEMBLE
LOCALENSEMBLE
LOCALENSEMBLE
LOCALENSEMBLE
STATS
STATS
STATS
STATS
STATS

NUM=4
NUM=4
NUM=4
NUM=4
NUM=4

NRES=100
NRES=100
NRES=100
NRES=100

DATA=data/
DATA=data/
DATA=data/
DATA=data/

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_.*)

TEMPLATE=chaina.pdb
TEMPLATE=chainb.pdb
TEMPLATE=chainc.pdb
TEMPLATE=chaind.pdb

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_.*)

NOPBC
NOPBC
NOPBC
NOPBC

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.6

MATHEVAL
This is part of the function module

Calculate a combination of variables using a matheval expression.
This action computes an arbitrary function of one or more precomputed 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).
If you want a function that depends not only on collective variables but also on time you can use the TIME action.

Attention
The MATHEVAL object only works if libmatheval is installed on the system and PLUMED has been linked to it

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
Generated by Doxygen

5.4 Functions

135

Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

ARG

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.

dAB: DISTANCE ATOMS=10,12
dAC: DISTANCE ATOMS=10,15
diff: MATHEVAL 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 MATHEVAL 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, which does not require libmatheval to be installed on your system.
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.

DISTANCE LABEL=d1 ATOMS=1,2 COMPONENTS
DISTANCE LABEL=d2 ATOMS=2,3 COMPONENTS
MATHEVAL ...
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
... MATHEVAL
PRINT ARG=theta
Generated by Doxygen

136

Collective variables

(See also PRINT and DISTANCE).
Notice that the matheval library 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
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)
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 MATHEVAL 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.
MATHEVAL 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.
# 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: MATHEVAL 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: MATHEVAL 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 [24].
Generated by Doxygen

5.4 Functions

5.4.6.1

137

TIME
This is part of the generic module

retrieve the time of the simulation to be used elsewere
Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

Examples

TIME
PRINT ARG=t1

LABEL=t1

(See also PRINT).

5.4.7

PIECEWISE
This is part of the function module

Compute a piecewise 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

Description

Generated
_pfuncby Doxygen
one

or multiple instances of this quantity will be referenceable 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 piecewise functions of each of the arguments.

138

Collective variables

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

Examples

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

(See also PRINT and DISTANCE).

5.4.8

SORT
This is part of the function module

This function can be used to sort colvars according to their magnitudes.

Description of components

Generated by Doxygen

5.4 Functions

139

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.
Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

ARG

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

d12:
d13:
d14:
d15:
sort:
PRINT

DISTANCE ATOMS=1,2
DISTANCE ATOMS=1,3
DISTANCE ATOMS=1,4
DISTANCE ATOMS=1,5
SORT ARG=d12,d13,d14,d15
ARG=sort.1,sort.4

(See also PRINT and DISTANCE).

5.4.9

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 store 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).
Generated by Doxygen

140

Collective variables

Description of components

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

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.
Generated by Doxygen

5.5 MultiColvar

141

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.*

5.5

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

g[f ({X}i )]

In this expression g is a funciton 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 dupilcating 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 .

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 ofcoordination 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 calculatethe 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 ofdistances such as the minimum, the number
less than a certain quantity and so on.

DISTANCES

FCCUBIC
INPLANEDISTANCES
MOLECULES
PLANES

Measure how similar the environment around atoms is to that found in a FCC
structure.
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.

Calculate 3rd order Steinhardt parameters.

Calculate 4th order Steinhardt parameters.

Calculate 6th order Steinhardt parameters.

SIMPLECUBIC

Calculate whether or not the coordination spheres of atoms are arranged as they
would be in a simplecubic 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.

XDISTANCES

Calculate the x components of the vectors connecting one or many pairs of
atoms.You can then calculate functions of the distribution ofvalues such as the
minimum, the number less than a certain quantity and so on.

Generated by Doxygen

142

Collective variables

XYDISTANCES

Calculate distance between a pair of atoms neglecting the z-component.You can
then calculate functions of the distribution ofvalues such as the minimum, the
number less than a certain quantity and so on.

XZDISTANCES

Calculate distance between a pair of atoms neglecting the y-component.You can
then calculate functions of the distribution ofvalues such as the minimum, the
number less than a certain quantity and so on.

YDISTANCES

YZDISTANCES

Calculate distance between a pair of atoms neglecting the x-component.You can
then calculate functions of the distribution ofvalues such as the minimum, the
number less than a certain quantity and so on.

ZDISTANCES

Calculate the z components of the vectors connecting one or many pairs of
atoms.You can then calculate functions of the distribution ofvalues such as the
minimum, the number less than a certain quantity and so on.

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:
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 quanties that are to be calculated from the atoms involved and any parameters
you need to specify what function of these base quanties 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

5.5 MultiColvar

143

MFILTER_BETWEEN

This action can be used to filter the colvar values calculated by a multicolvarso 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 multicolvarso 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 multicolvarso 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 collectivevariables
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 collectivevariables
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 collectivevariables
for the atoms that lie in a particular, user-specified part of of the cell.

INSPHERE

This quantity can be used to calculate functions of the distribution of collectivevariables
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 variablesfor 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:

w({X}i )g[f ({X}i )]

can be evaluated where once again g is a function with one argumet 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 [25] 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 torsions between axis of 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 vectoron
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 vectoron
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 vectoron
the atoms in the first coordination sphere.

NLINKS

Calculate number of pairs of atoms/molecules that are "linked"

SMAC

Calculate a variant on the SMAC collective variable discussed in [26]

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
Generated by Doxygen

144

Collective variables

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 useed to transform the colvar values calculated by a multicolvar using a histogrambead

MTRANSFORM_LESS

This action can be useed to transform the colvar values calculated by a multicolvar using a switchingfunction

MTRANSFORM_MORE

This action can be useed 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:

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:
UWALLS

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 forcefield or to implement
your forcefield.

5.5.3

ANGLES
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) =

g(θijk )

ijk

Alternatively you can use this command to calculate functions such as:

f (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 [27].
Generated by Doxygen

5.5 MultiColvar

145

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 amongst 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 the label of the components customizable. 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

mean

MEAN

the mean value. The output component can be refererred 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

ATOMS

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 conjuction 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.

Generated by Doxygen

146

Collective variables

Or alternatively by using

GROUPC

This must be used in conjuction 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

MEAN

LESS_THAN

BETWEEN

HISTOGRAM

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

Generated by Doxygen

5.5 MultiColvar

147

Examples

The following example instructs plumed to find the average of two angles and to print it to a 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

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. A
discretized-normalized histogram of the distribution is then output

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.4

BRIDGE
This is part of the multicolvar module

Calculate the number of atoms that bridge two parts of a structure
This quantity calculates:

f (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

ATOMS

Or alternatively by using

Generated by Doxygen

148

Collective variables

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 parallelize

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 betweeen
atoms 1-10 and atoms 11-20 and to print the value to a file

BRIDGE BRIDGING_ATOMS=100-200 GROUPA=1-10 GROUPB=11-20 LABEL=w1
PRINT ARG=a1.mean FILE=colvar

5.5.5

COORDINATIONNUMBER
This is part of the multicolvar module

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

n
m

Description of components

Generated by Doxygen

5.5 MultiColvar

149

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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 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

150

Collective variables

SPECIESA

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 cooordination numbers specifies how many of the atoms specifies using SPEC←IESB is within the specified cutoff. As with the species keyword the input can also be specified
using the label of another multicolvar

SPECIESB

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

( default=6 ) The n parameter of the switching function

( 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

SWITCH

MEAN

MORE_THAN

LESS_THAN

Generated by Doxygen

5.5 MultiColvar

MAX

151

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

MIN

min

BETWEEN

HISTOGRAM

log

exp

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 a discretized histogram of the distribution of values. This shortcut
allows you to calculates NBIN quantites like BETWEEN. The final value can
be referenced using label.histogram. You can use multiple instances of this
keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRAM3... The corresponding values are then referenced using label.histogram-1, label.histogram2, 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.

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 tells plumed to calculate the coordination numbers of atoms 1-100 with themselves. The minimum coordination number is then calculated.
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.
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}

5.5.6

DENSITY

Generated by Doxygen

152

Collective variables

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

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 parallelize

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.

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.7

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

Generated by Doxygen

5.5 MultiColvar

153

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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 atoms involved can be specified using

ATOMS

Or alternatively by using

GROUP

Generated by Doxygen

Calculate the distance between each distinct pair of atoms in the group

154

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 conjuction with GROUPB.

GROUPB

Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjuction 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

ALT_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

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

is calculated using

LESS_THAN

log

exp

max = β log

exp

si
β

The value of β in this function is

Generated by Doxygen

5.5 MultiColvar

155

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...
calculate a discretized histogram of the distribution of values. This shortcut
allows you to calculates NBIN quantites like BETWEEN. The final value can
be referenced using label.histogram. You can use multiple instances of this
keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRAM3... The corresponding values are then referenced using label.histogram-1, label.histogram2, 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.

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.
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.
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.
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.
Generated by Doxygen

156

Collective variables

DISTANCES GROUPA=1 GROUPB=2,3 MORE_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.gt0.1

(See also PRINT switchingfunction)

Calculating minimum distances

To calculate and print the minimum distance between two groups of atoms you use the following commands

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 differentiability the minimum is calculated using the following function:

s=
log

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 coordinatetion 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:

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.8

FCCUBIC

This is part of the crystallization module
It is only available if you configure PLUMED with ./configure –enable-modules=crystallization . Furtherby Doxygen
more, this feature is still being developed so take care when using it and report anyGenerated
problems
on the
mailing list.

5.5 MultiColvar

157

Measure how similar the environment around atoms is to that found in a FCC structure.
This CV was introduced in this article [28] and again in this article [29] 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

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:

80080
2717 + 16α

and

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

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities calculated by this action

Generated by Doxygen

158

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 refererred 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 atoms involved can be specified using

SPECIES

Or alternatively by using

SPECIESA

SPECIESB

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

( default=6 ) The n parameter of the switching function

( 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

159

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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

SWITCH

MEAN

MORE_THAN

LESS_THAN

quantity

MAX

is calculated using

MIN

BETWEEN

HISTOGRAM

Generated by Doxygen

max = β log

exp

si
β

The value of β in this function is

min

log

exp

160

Collective variables

MOMENTS

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 calculates the FCCUBIC parameter for the 64 atoms in the system and then calculates and
prints the average value for this quantity.

FCCUBIC SPECIES=1-64 SWITCH={RATIONAL D_0=3.0 R_0=1.5} MEAN LABEL=d
PRINT ARG=d.* FILE=colv

5.5.9

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
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

5.5 MultiColvar

161

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 amongst 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 the label of the components customizable. 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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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 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 defin the normal to the plane of interest. For more
information on how to specify lists of atoms see Groups and Virtual Atoms

Or alternatively by using

GROUP

The set of atoms for which you wish to calculate the in plane distance

Options

NUMERICAL_DERIVATIVES

Generated by Doxygen

( default=off ) calculate the derivatives for these quantities numerically

162

NOPBC

Collective variables

SERIAL

( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

ALT_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

MEAN

MIN

MAX

min

MORE_THAN

BETWEEN

exp

quantity
is calculated using

LESS_THAN

log

max = β log

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

163

HISTOGRAM

calculate a discretized histogram of the distribution of values. This shortcut
allows you to calculates NBIN quantites like BETWEEN. The final value can
be referenced using label.histogram. You can use multiple instances of this
keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRAM3... The corresponding values are then referenced using label.histogram-1, label.histogram2, 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.

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.

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.10

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

164

Collective variables

Quantity

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

VMEAN

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.

MOLECULES MOL1=1,2 MOL2=3,4 MOL3=5,6 MOL4=7,8 MEAN LABEL=mm
PRINT ARG=mm.mean FILE=colvar

5.5.11

PLANES

Calculate the plane perpendicular to two vectors in order to represent the orientation of a planar molecule.
Generated by Doxygen

5.5 MultiColvar

165

Description of components

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred 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 centre for the three/four 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

VMEAN

Examples

Generated by Doxygen

166

Collective variables

5.5.12

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) =

σ(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
Q3 (i) = t
q3m (i)∗ q3m (i)
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.
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

Generated by Doxygen

5.5 MultiColvar

167

Quantity

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred 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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities calculated by this action

mean

MEAN

the mean value. The output component can be refererred 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 atoms involved can be specified using

SPECIES

Or alternatively by using

SPECIESA

SPECIESB

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

168

Collective variables

( default=12 ) The n parameter of the switching function

( 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

SWITCH

MEAN

LESS_THAN

MORE_THAN

VMEAN

BETWEEN

HISTOGRAM

Generated by Doxygen

5.5 MultiColvar

169

MOMENTS

MIN

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

exp

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 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:

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:

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 paramters that describe the arrangement of chlorine ions
around the sodium atoms in NaCl. 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 paramter
is calculated and output to a file called colvar

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.13

170

Collective variables

Calculate 4th order Steinhardt parameters.
The 4th 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) =

σ(rij )Y4m (rij )
P
j σ(rij )

where Y4m is one of the 4th 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.

v
u 4
u X
q4m (i)∗ q4m (i)
Q4 (i) = t
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

Generated by Doxygen

5.5 MultiColvar

171

Quantity

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred 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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities calculated by this action

mean

MEAN

the mean value. The output component can be refererred 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 atoms involved can be specified using

SPECIES

Or alternatively by using

SPECIESA

SPECIESB

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

172

Collective variables

( default=12 ) The n parameter of the switching function

( 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

SWITCH

MEAN

LESS_THAN

MORE_THAN

VMEAN

BETWEEN

HISTOGRAM

Generated by Doxygen

5.5 MultiColvar

173

MOMENTS

MIN

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

exp

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 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:

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:

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 paramters that describe the arrangement of chlorine ions
around the sodium atoms in NaCl. 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 paramter
is calculated and output to a file called colvar

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.14

174

Collective variables

Calculate 6th order Steinhardt parameters.
The 6th 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) =

σ(rij )Y6m (rij )
P
j σ(rij )

where Y6m is one of the 6th 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.

v
u 6
u X
q6m (i)∗ q6m (i)
Q6 (i) = t
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

Generated by Doxygen

5.5 MultiColvar

175

Quantity

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred 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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities calculated by this action

mean

MEAN

the mean value. The output component can be refererred 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 atoms involved can be specified using

SPECIES

Or alternatively by using

SPECIESA

SPECIESB

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

176

Collective variables

( default=12 ) The n parameter of the switching function

( 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

SWITCH

MEAN

LESS_THAN

MORE_THAN

VMEAN

BETWEEN

HISTOGRAM

Generated by Doxygen

5.5 MultiColvar

177

MOMENTS

MIN

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

exp

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 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:

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:

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 paramters that describe the arrangement of chlorine ions
around the sodium atoms in NaCl. 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 paramter
is calculated and output to a file called colvar

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.15

SIMPLECUBIC

178

Collective variables

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

4
4
x4ij +yij
+zij
4
rij

σ(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.

Description of components

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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

5.5 MultiColvar

179

The atoms involved can be specified using

SPECIES

Or alternatively by using

SPECIESA

SPECIESB

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

( default=6 ) The n parameter of the switching function

( 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

SWITCH

Generated by Doxygen

180

Collective variables

MEAN

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

MAX

is calculated using

MIN

BETWEEN

HISTOGRAM

max = β log

exp

si
β

The value of β in this function is

min

log

exp

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.

ALT_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

min

Generated by Doxygen

5.5 MultiColvar

181

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.

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

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.16

TETRAHEDRAL

Calculate the degree to which the environment about ions has a tetrahedral order.
We can measure the degree to which the first coordination shell around any atom, i is tetrahedrally ordered 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 fo 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

Generated by Doxygen

182

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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 atoms involved can be specified using

SPECIES

Or alternatively by using

SPECIESA

SPECIESB

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

183

( default=6 ) The n parameter of the switching function

( 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

SWITCH

MEAN

MORE_THAN

LESS_THAN

MAX

is calculated using

MIN

max = β log

exp

si
β

The value of β in this function is

min

log

exp

Generated by Doxygen

184

Collective variables

BETWEEN

HISTOGRAM

MOMENTS

ALT_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

min

Examples

The following command calculates the average value of the tetrahedrality parameter for a set of 64 atoms all of the
same type and outputs this quantity to a file called colvar.

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 tetrahedrality 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.

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.17

TORSIONS
This is part of the multicolvar module

Calculate whether or not a set of torsional angles are within a particular range.
Generated by Doxygen

5.5 MultiColvar

185

Description of components

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

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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

BETWEEN

HISTOGRAM

Generated by Doxygen

186

Collective variables

Examples

The following provides an example of the input for the torsions command

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

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

5.5.18

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

Generated by Doxygen

5.5 MultiColvar

187

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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 atoms involved can be specified using

ATOMS

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 conjuction with GROUPB.

GROUPB

Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjuction with GROUPA.

Options

Generated by Doxygen

188

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 parallelize

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

min

log

exp

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

BETWEEN

Generated by Doxygen

5.5 MultiColvar

189

HISTOGRAM

MOMENTS

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

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.

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.

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.

XDISTANCES GROUPA=1 GROUPB=2,3 MORE_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.gt0.1

(See also PRINT switchingfunction)

5.5.19

XYDISTANCES

Generated by Doxygen

190

Collective variables

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

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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 atoms involved can be specified using

Generated by Doxygen

5.5 MultiColvar

ATOMS

191

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 conjuction with GROUPB.

GROUPB

Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjuction 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 parallelize

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

Generated by Doxygen

max = β log

exp

si
β

The value of β in this function is

min

192

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

LESS_THAN

LOWEST

log

exp

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

BETWEEN

HISTOGRAM

MOMENTS

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
XYDISTANCES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min

(See also PRINT).

5.5.20

XZDISTANCES

Generated by Doxygen

5.5 MultiColvar

193

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

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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 atoms involved can be specified using

Generated by Doxygen

194

ATOMS

Collective variables

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 conjuction with GROUPB.

GROUPB

Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjuction 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 parallelize

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

exp

si
β

The value of β in this function is

min

Generated by Doxygen

5.5 MultiColvar

MIN

195

calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β

min

LESS_THAN

LOWEST

log

exp

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

BETWEEN

HISTOGRAM

MOMENTS

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
XZDISTANCES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min

(See also PRINT).

5.5.21

YDISTANCES

Generated by Doxygen

196

Collective variables

This is part of the multicolvar module

Description of components

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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 atoms involved can be specified using

Generated by Doxygen

5.5 MultiColvar

ATOMS

197

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 conjuction with GROUPB.

GROUPB

Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjuction 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 parallelize

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

Generated by Doxygen

max = β log

exp

si
β

The value of β in this function is

min

198

MIN

LESS_THAN

LOWEST

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

exp

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

BETWEEN

HISTOGRAM

MOMENTS

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

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.
Generated by Doxygen

5.5 MultiColvar

199

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.

YDISTANCES GROUP=1-3 AVERAGE LABEL=d1
PRINT ARG=d1.average

YDISTANCES GROUPA=1 GROUPB=2,3 MORE_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.gt0.1

(See also PRINT switchingfunction)

5.5.22

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

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

Generated by Doxygen

200

Collective variables

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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 atoms involved can be specified using

ATOMS

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 conjuction with GROUPB.

GROUPB

Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjuction with GROUPA.

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 parallelize

SERIAL

Generated by Doxygen

5.5 MultiColvar

201

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

LESS_THAN

LOWEST

max = β log

exp

si
β

The value of β in this function is

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

exp

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

BETWEEN

HISTOGRAM

Generated by Doxygen

202

Collective variables

MOMENTS

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

YZDISTANCES ATOMS1=3,5 ATOMS2=1,2 MIN={BETA=0.1} LABEL=d1
PRINT ARG=d1.min

(See also PRINT).

5.5.23

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

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

Generated by Doxygen

5.5 MultiColvar

203

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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 atoms involved can be specified using

ATOMS

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 conjuction with GROUPB.

GROUPB

Calculate the distances between all the atoms in GROUPA and all the atoms in GROUPB. This
must be used in conjuction 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

Generated by Doxygen

204

Collective variables

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

min

log

exp

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

BETWEEN

HISTOGRAM

Generated by Doxygen

5.5 MultiColvar

MOMENTS

205

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

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.

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.

ZDISTANCES GROUP=1-3 AVERAGE LABEL=d1
PRINT ARG=d1.average

ZDISTANCES GROUPA=1 GROUPB=2,3 MORE_THAN={RATIONAL R_0=0.1}
PRINT ARG=d1.gt0.1

(See also PRINT switchingfunction)

5.5.24

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.
Generated by Doxygen

206

Collective variables

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 practise 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 =

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.

Description of components

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred 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 quantitities calculated by this action

lowest

LOWEST

the lowest of the quantitities 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 refererred 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

Generated by Doxygen

5.5 MultiColvar

207

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 ammount 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

VMEAN

MEAN

MOMENTS

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

exp

max = β log

exp

si
β

The value of β in this function is

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

208

Collective variables

BEAD

This keywords is used if you want to employ an alternative to the function defeind 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

DISTANCES GROUPA=1 GROUPB=2-50 MEAN LABEL=d1
MFILTER_BETWEEN DATA=d1 LOWER=0 UPPER=3.0 SMEAR=0.0001 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 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.

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.25

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 practise 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

Generated by Doxygen

5.5 MultiColvar

209

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred 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 quantitities calculated by this action

lowest

LOWEST

the lowest of the quantitities 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 refererred 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

( default=6 ) The n parameter of the switching function

( 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 parallelize

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

210

Collective variables

VMEAN

MEAN

MOMENTS

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

exp

MAX

is calculated using

ALT_MIN

max = β log

exp

si
β

The value of β in this function is

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

Examples

The example shown below calculates the mean for those distances that less than 1.5 nm in length

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.26

MFILTER_MORE
This is part of the multicolvar module
Generated by Doxygen

5.5 MultiColvar

211

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 practise 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

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred 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 quantitities calculated by this action

lowest

LOWEST

the lowest of the quantitities 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 refererred 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

212

Collective variables

Compulsory keywords

DATA

The multicolvar that calculates the set of base quantities that we are interested in

( default=6 ) The n parameter of the switching function

( 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

VMEAN

MEAN

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.

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

LOWEST

exp

is calculated using

ALT_MIN

log

max = β log

exp

si
β

The value of β in this function is

min

this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest
Generated by Doxygen

5.5 MultiColvar

213

HIGHEST

this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest

SWITCH

Examples

The example shown below calculates the mean for those distances that greater than 1.5 nm in length

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.

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.27

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

w(xi , yi , zi )

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:

w(xi , yi , zi ) =
xl

dxdydzK

x − xi
σ

y − yi
σ

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
Generated by Doxygen

214

Collective variables

Description of components

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred to elsewhere in the input file by using the label.vmean

between

BETWEEN

lessthan

LESS_THAN

mean

MEAN

the mean value. The output component can be refererred to elsewhere in the
input file by using the label.mean

morethan

MORE_THAN

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

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).
Generated by Doxygen

5.5 MultiColvar

215

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 parallelize

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

MEAN

LESS_THAN

MORE_THAN

BETWEEN

HISTOGRAM

Examples

Generated by Doxygen

216

Collective variables

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.

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.28

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 )

where R is a rotation matrix that is calculated by constructing a set of three orthonormal vectors from the refererence
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:

w(ui , vi , wi ) =
0

dudvdwK

u − ui
σ

v − vi
σ

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

Generated by Doxygen

5.5 MultiColvar

217

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred to elsewhere in the input file by using the label.vmean

between

BETWEEN

lessthan

LESS_THAN

mean

MEAN

the mean value. The output component can be refererred to elsewhere in the
input file by using the label.mean

morethan

MORE_THAN

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 parallelize

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

218

Collective variables

OUTSIDE

( default=off ) calculate quantities for colvars that are on atoms outside the
region of interest

PRINT_BOX

( default=off ) write out the positions of the corners of the box to an xyz file

VMEAN

MEAN

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

FILE
UNITS

Examples

The following commands tell plumed to calculate the number of atoms in an ion chanel in a protein. The extent of
the chanel is calculated from the positions of atoms 1, 4, 5 and 11. The final value will be labeled cav.
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
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
Generated by Doxygen

5.5 MultiColvar

5.5.29

219

INCYLINDER
This is part of the multicolvar module

P
sτ =

f (si )w(xi , yi , zi )
iP
i

w(xi , yi , zi )

w(xi , yi , zi ) =

where σ is a switchingfunction. 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

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred to elsewhere in the input file by using the label.vmean

between

BETWEEN

lessthan

LESS_THAN

Generated
mean by Doxygen
MEAN

morethan

MORE_THAN

the mean value. The output component can be refererred to elsewhere in the
input file by using the label.mean
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.

220

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

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 cyclinder 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 parallelize

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

MEAN

LESS_THAN

MORE_THAN

Generated by Doxygen

5.5 MultiColvar

BETWEEN

HISTOGRAM

SIGMA

221

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.

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.30

INSPHERE
This is part of the multicolvar module

P
sτ =

f (si )w(xi , yi , zi )
iP
i

w(xi , yi , zi )

w(xi , yi , zi ) =
where σ is a switchingfunction. 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
Generated by Doxygen

222

Collective variables

Description of components

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred to elsewhere in the input file by using the label.vmean

between

BETWEEN

lessthan

LESS_THAN

mean

MEAN

the mean value. The output component can be refererred to elsewhere in the
input file by using the label.mean

morethan

MORE_THAN

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 sphereical region of interest

Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances
Generated by Doxygen

5.5 MultiColvar

223

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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

MEAN

LESS_THAN

MORE_THAN

BETWEEN

HISTOGRAM

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.

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.31

TETRAHEDRALPORE

Generated by Doxygen

224

Collective variables

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:

f (si )w(ui , vi , wi )
iP

sτ =

w(ui , vi , wi )

( 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 refererence
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
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

and

v2 = cos

π
4

b − sin

π
4

In the previous function w(ui , vi , wi ) measures whether or not the system is in the subregion of interest. It is equal
to:

w(ui , vi , wi ) =
0

dudvdwK

u − ui
σ

v − vi
σ

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

Generated by Doxygen

5.5 MultiColvar

225

Quantity

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred to elsewhere in the input file by using the label.vmean

between

BETWEEN

lessthan

LESS_THAN

mean

MEAN

the mean value. The output component can be refererred to elsewhere in the
input file by using the label.mean

morethan

MORE_THAN

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 parallelize

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

MEAN

Generated by Doxygen

226

Collective variables

LESS_THAN

MORE_THAN

BETWEEN

HISTOGRAM

FILE
UNITS

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...
calculate a discretized histogram of the distribution of values. This shortcut
allows you to calculates NBIN quantites like BETWEEN. The final value can
be referenced using label.histogram. You can use multiple instances of this
keyword i.e. HISTOGRAM1, HISTOGRAM2, HISTOGRAM3... The corresponding values are then referenced using label.histogram-1, label.histogram2, label.histogram-3...
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.

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

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.32

GRADIENT

Generated by Doxygen

5.5 MultiColvar

227

Calculate the gradient of the average value of a multicolvar value
This command allows you to calculate the collective variable discussed in [30].

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

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 graident. 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 parallelize

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 [30] in order to detect
whether or not atoms are distributed uniformly along the x-axis of the simulation cell.
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.
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
Generated by Doxygen

228

5.5.33

Collective variables

INTERMOLECULARTORSIONS

Generated by Doxygen

5.5 MultiColvar

229

Calculate torsions between axis of adjacent molecules
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 M←OLA one atom from MOLB 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 M←OLA one atom from MOLB will be computed. This should be the label/s of MOLECULES or PLANES
actions

Compulsory keywords

Options

Generated by Doxygen

( default=6 ) The n parameter of the switching function

( 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

230

Collective variables

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

LOWMEM

( default=off ) lower the memory requirements

SWITCH

This keyword is used if you want to employ an alternative to the continuous swiching 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 centeres 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 tt_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.

m1: MOLECULES MOL1=1,2 MOL2=3,4 MOL3=5,6 MOL4=7,8
tt_p: INTERMOLECULARTORSIONS MOLS=m1 SWITCH={RATIONAL R_0=0.25 D_0=2.0 D_MAX=3.0}
htt_p: HISTOGRAM DATA=tt_p GRID_MIN=-pi GRID_MAX=pi BANDWIDTH=0.1 GRID_BIN=200 STRIDE=1
DUMPGRID GRID=htt_p FILE=myhist.out

5.5.34

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 4th 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 [25] 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:

si =

ci +

σ(rij )cj

σ(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
Generated by Doxygen

5.5 MultiColvar

231

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-centred 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

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred to elsewhere in the input file by using the label.vmean

vsum

VSUM

the norm of sum of vectors. The output component can be refererred to elsewhere
in the input file by using the label.vsum

between

BETWEEN

lessthan

LESS_THAN

mean

MEAN

the mean value. The output component can be refererred 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 atoms involved can be specified using

SPECIES

Generated by Doxygen

232

Collective variables

Or alternatively by using

SPECIESA

SPECIESB

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

( default=6 ) The n parameter of the switching function

( 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

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

LOWMEM

( default=off ) lower the memory requirements

SWITCH

This keyword is used if you want to employ an alternative to the continuous swiching 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, MEAN2, MEAN3... The corresponding
values are then referenced using label.mean-1, label.mean-2, label.mean-3...

MORE_THAN

calculate
P the number of variables 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_THA←N1, MORE_THAN2, MORE_THAN3... The corresponding values are then referenced using
label.morethan-1, label.morethan-2, label.morethan-3...

LESS_THAN

calculate
P the number of 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_T←HAN2, LESS_THAN3... The corresponding values are then referenced using label.lessthan-1,
label.lessthan-2, label.lessthan-3...

BETWEEN

Generated by Doxygen

5.5 MultiColvar

233

HISTOGRAM

calculate a discretized histogram of the distribution of values. This shortcut allows you
to calculates NBIN quantites like BETWEEN. The final value can be referenced using label.histogram. You can use multiple instances of this keyword i.e. HISTOGRAM1, HISTOGR←AM2, HISTOGRAM3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...

MOMENTS

calculate the moments of theP
distribution of collective variables. The mth moment of a distriN
1
m
bution 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.

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.vmean3...
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. VSUM1, VSUM2, VSUM3... The corresponding values are then referenced using label.vsum-1, label.vsum-2, label.vsum-3...

VSUM

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.

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

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 outputeed
to a file. This calculates the quantities that were used in the paper by Lechner and Dellago [25]

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.35

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.
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
Generated by Doxygen

234

Collective variables

- 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 parameteters 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 =

σ(rij )

∗
q3m
(i)q3m (j)
Pm=−3
j σ(rij )

where q3m (i) and q3m (j) are the 3rd order Steinhardt vectors calculated for atom i and atom j respectively and the
asterix 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

Generated by Doxygen

5.5 MultiColvar

235

Quantity

Keyword

Description

between

BETWEEN

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities calculated by this action

mean

MEAN

the mean value. The output component can be refererred 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 atoms involved can be specified using

SPECIES

Or alternatively by using

SPECIESA

SPECIESB

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

( default=6 ) The n parameter of the switching function

( 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

236

Collective variables

R←_0

The r_0 parameter of the switching function

Options

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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 swiching 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

MORE_THAN

LESS_THAN

calculate the number of variables less than a certain target value. This quantity is calculated
P
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_T←HAN2, 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 specified using (BETA= β ) The
P
β

MIN

min

log

exp

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.min-3...
BETWEEN

HISTOGRAM

calculate a discretized histogram of the distribution of values. This shortcut allows you
to calculates NBIN quantites like BETWEEN. The final value can be referenced using label.histogram. You can use multiple instances of this keyword i.e. HISTOGRAM1, HISTOGR←AM2, HISTOGRAM3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...

MOMENTS

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

Generated by Doxygen

5.5 MultiColvar

237

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.

Q3 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q3
LOCAL_Q3 ARG=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.

Q3 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q3
LOCAL_Q3 ARG=q3 SWITCH={RATIONAL D_0=1.3 R_0=0.2} HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1}
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

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 ARG=q3a,q3b SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LOWMEM LABEL=w3
PRINT ARG=w3.* FILE=colvar

5.5.36

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.
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:
Generated by Doxygen

238

Collective variables

• 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 parameteters 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 =

σ(rij )

∗
q4m
(i)q4m (j)
Pm=−4
j σ(rij )

where q4m (i) and q4m (j) are the 4th order Steinhardt vectors calculated for atom i and atom j respectively and the
asterix 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

Keyword

Description

between

BETWEEN

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities calculated by this action

mean

MEAN

the mean value. The output component can be refererred 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.
Generated by Doxygen
You can calculate this quantity multiple times using different parameters.

5.5 MultiColvar

239

The atoms involved can be specified using

SPECIES

Or alternatively by using

SPECIESA

SPECIESB

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

( default=6 ) The n parameter of the switching function

( 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

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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 swiching 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

MORE_THAN

Generated by Doxygen

240

LESS_THAN

MIN

Collective variables

min

log

exp

HISTOGRAM

calculate a discretized histogram of the distribution of values. This shortcut allows you
to calculates NBIN quantites like BETWEEN. The final value can be referenced using label.histogram. You can use multiple instances of this keyword i.e. HISTOGRAM1, HISTOGR←AM2, HISTOGRAM3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...

MOMENTS

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.
Q4 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q4
LOCAL_Q4 ARG=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.
Q4 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q4
LOCAL_Q4 ARG=q4 SWITCH={RATIONAL D_0=1.3 R_0=0.2} HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1}
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
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 ARG=q4a,q4b SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LOWMEM LABEL=w4
PRINT ARG=w4.* FILE=colvar
Generated by Doxygen

5.5 MultiColvar

5.5.37

LOCAL_Q6

Generated by Doxygen

241

242

Collective variables

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 parameteters 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 =

σ(rij )

∗
q6m
(i)q6m (j)
Pm=−6
σ(r
)
ij
j

where q6m (i) and q6m (j) are the 6th order Steinhardt vectors calculated for atom i and atom j respectively and the
asterix 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

Generated by Doxygen

5.5 MultiColvar

243

Keyword

Description

between

BETWEEN

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities calculated by this action

mean

MEAN

the mean value. The output component can be refererred 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 atoms involved can be specified using

SPECIES

Or alternatively by using

SPECIESA

Generated by Doxygen

244

SPECIESB

Collective variables

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

( default=6 ) The n parameter of the switching function

( 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

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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 swiching 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

MORE_THAN

LESS_THAN

MIN

min

log

exp

HISTOGRAM

calculate a discretized histogram of the distribution of values. This shortcut allows you
to calculates NBIN quantites like BETWEEN. The final value can be referenced using label.histogram. You can use multiple instances of this keyword i.e. HISTOGRAM1, HISTOGR←AM2, HISTOGRAM3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...
Generated by Doxygen

5.5 MultiColvar

245

MOMENTS

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.

Q6 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q6
LOCAL_Q6 ARG=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.

Q6 SPECIES=1-64 D_0=1.3 R_0=0.2 LABEL=q6
LOCAL_Q6 ARG=q6 SWITCH={RATIONAL D_0=1.3 R_0=0.2} HISTOGRAM={GAUSSIAN LOWER=0.0 UPPER=1.0 NBINS=20 SMEAR=0.1}
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

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 ARG=q4a,q4b SWITCH={RATIONAL D_0=1.3 R_0=0.2} MEAN LOWMEM LABEL=w4
PRINT ARG=w6.* FILE=colvar

5.5.38

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

Generated by Doxygen

246

Collective variables

GROUP

. For more information on how to specify lists of atoms see Groups and Virtual Atoms

Or alternatively by using

GROUPA
GROUPB

Compulsory keywords

( default=6 ) The n parameter of the switching function

( 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

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

LOWMEM

( default=off ) lower the memory requirements

SWITCH

This keyword is used if you want to employ an alternative to the continuous swiching 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.
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 neighbouring atoms in a system containg 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"
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.39

SMAC

Generated by Doxygen

5.5 MultiColvar

247

Calculate a variant on the SMAC collective variable discussed in [26]
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 alignment 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−ψ
j6=i σ(rij )
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 moleclues 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

Generated by Doxygen

248

Collective variables

Quantity

Keyword

Description

between

BETWEEN

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities calculated by this action

mean

MEAN

the mean value. The output component can be refererred 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 atoms involved can be specified using

SPECIES

Or alternatively by using

SPECIESA

SPECIESB

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

( default=6 ) The n parameter of the switching function

( 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
Generated by Doxygen

5.5 MultiColvar

249

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

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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 swiching 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

MORE_THAN

LESS_THAN

MIN

min

log

exp

HISTOGRAM

calculate a discretized histogram of the distribution of values. This shortcut allows you
to calculates NBIN quantites like BETWEEN. The final value can be referenced using label.histogram. You can use multiple instances of this keyword i.e. HISTOGRAM1, HISTOGR←AM2, HISTOGRAM3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...

MOMENTS

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

250

Collective variables

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
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 .

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.

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.40

MTRANSFORM_BETWEEN
This is part of the multicolvar module
Generated by Doxygen

5.5 MultiColvar

251

This action can be useed 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:

fi =

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
thia action one computes:

PN
µ=

i=1

In other words, you are calculating the mean for the transformed colvar.

Description of components

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred 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 quantitities calculated by this action

lowest

LOWEST

the lowest of the quantitities 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 refererred to elsewhere in the input
file by using the label.mean

Generated by Doxygen

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 refer-

252

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 ammount 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

VMEAN

MEAN

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.

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

LOWEST

log

exp

max = β log

exp

si
β

The value of β in this function is

min

this flag allows you to recover the lowest of these variables. The final value can
be referenced using label.lowest

Generated by Doxygen

5.5 MultiColvar

253

HIGHEST

this flag allows you to recover the highest of these variables. The final value
can be referenced using label.highest

BEAD

Examples

The following input gives an example of how a MTRANSFORM_BETWEEN action can be used to duplicate functionality that is elsehwere in PLUMED.

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:

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.41

MTRANSFORM_LESS
This is part of the multicolvar module

This action can be useed 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 )
where σ is the switchingfunction. In this action by contrast the colvar is being transformed by the switchingfunction.
If one thus calculates a MEAN for thia action one computes:
Generated by Doxygen

254

Collective variables

PN
µ=

i=1 (si )

In other words, you are calculating the mean for the transformed colvar.

Description of components

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred 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 quantitities calculated by this action

lowest

LOWEST

the lowest of the quantitities 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 refererred 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

( default=6 ) The n parameter of the switching function

( 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

Generated by Doxygen

5.5 MultiColvar

255

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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

VMEAN

MEAN

MOMENTS

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

exp

quantity

max = β log

exp

si
β

The value of β in this function is

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

Examples

The following input gives an example of how a MTRANSFORM_LESS action can be used to duplicate functionality
that is elsehwere in PLUMED.
Generated by Doxygen

256

Collective variables

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:

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.42

MTRANSFORM_MORE
This is part of the multicolvar module

This action can be useed 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.

Description of components

5.5 MultiColvar

257

Generated by Doxygen

258

Collective variables

Quantity

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred 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 quantitities calculated by this action

lowest

LOWEST

the lowest of the quantitities 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 refererred 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

( default=6 ) The n parameter of the switching function

( 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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

VMEAN

MEAN

MOMENTS

Generated by Doxygen

5.5 MultiColvar

MIN

259

calculate the minimum value. To make this quantity continuous the minimum is
β
The value of β in this function is speccalculated using
=
P
β

min

log

exp

quantity

MAX

is calculated using

ALT_MIN

max = β log

exp

si
β

The value of β in this function is

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

Examples

The following input gives an example of how a MTRANSFORM_MORE action can be used to duplicate functionality
that is elsehwere in PLUMED.
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:
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.43

UWALLS

Generated by Doxygen

260

Collective variables

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

Description

bias

the instantaneous value of the bias potentials

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 refererred to elsewhere in the input file by using the label.vmean

vsum

VSUM

the norm of sum of vectors. The output component can be refererred to elsewhere
in the input file by using the label.vsum

spath

SPATH

the position on the path

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred to elsewhere in the
input file by using the label.mean
Generated by Doxygen

5.6 Exploiting contact matrices

261

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

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.

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

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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
centre 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 centre of mass of the cluster.
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 definining
Generated by Doxygen

262

Collective variables

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 centre's 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 molecules are adjacent if they are within a certain cutoff
and if the angle between them is within certain ranges.

SMAC_MATRIX

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

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.

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

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
Generated by Doxygen

5.6 Exploiting contact matrices

263

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 analysed using a number of other algorithms as is detailed in
[31].
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

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 parallelize

SERIAL
TIMINGS
HIGHMEM

Generated by Doxygen

( 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

264

Collective variables

SWITCH

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 centeres
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.

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}
rr: ROWSUMS MATRIX=mat MORE_THAN={RATIONAL D_0=1.0 R_0=0.1}
PRINT ARG=rr.* FILE=colvar

5.6.2

CONTACT_MATRIX

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 analysed using a number of other algorithms as is detailed in
[31].
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

Generated by Doxygen

5.6 Exploiting contact matrices

ATOMS

265

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 parallelize

SERIAL
TIMINGS
HIGHMEM
SWITCH

( 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
This keyword is used if you want to employ an alternative to the continuous
swiching 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. 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.

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

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
Generated by Doxygen

266

Collective variables

adjacent or not. These matrices can then be further analysed using a number of other algorithms as is detailed in
[31].
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 asymetric. 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.

Description of components

Keyword

Description

sum

SUM

the sum of values

The atoms involved can be specified using

Generated by Doxygen

5.6 Exploiting contact matrices

267

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 specifiedas 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

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 parallelize

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

Generated by Doxygen

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...

Examples

The following input can be used to analyse 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 its hydrogens to the neighbouring 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.

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

SMAC_MATRIX

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 )

Kn (θij )

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
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 moleclues 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
Generated
by Doxygen
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

5.6 Exploiting contact matrices

269

Or alternatively by using

ATOMSA

ATOMSB

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 parallelize

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

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
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 connectes molecules is output to a colvar 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 ...
Generated by Doxygen

270

Collective variables

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.5

CLUSTER_WITHSURFACE

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 analysing 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 sucessfully in the forward flux sampling simulations described in
this paper [32]

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 atom

Options

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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
Generated by Doxygen

5.6 Exploiting contact matrices

271

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.

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.6

COLUMNSUMS

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

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

Generated by Doxygen

272

Collective variables

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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

Compulsory keywords

MAT←RIX

the action that calcualtes the adjacency matrix vessel we would like to analyse

Options

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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 minimumPvalue. To make this quantity continuous the minimum is calculated
using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BE←TA= β ). 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

MIN

calculate the minimum value. To make this quantity continuous the minimum is calculated
β
using
=
The value of β in this function is specified using (BETA= β ) The
P
β

min

log

exp

Generated by Doxygen

5.6 Exploiting contact matrices

MAX

273

calculate the maximum value.
make this quantity continuous the maximum is calculated
To
using

max

= β log

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...
LESS_THAN

MORE_THAN

BETWEEN

HISTOGRAM

calculate a discretized histogram of the distribution of values. This shortcut allows you
to calculates NBIN quantites like BETWEEN. The final value can be referenced using label.histogram. You can use multiple instances of this keyword i.e. HISTOGRAM1, HISTOGR←AM2, HISTOGRAM3... The corresponding values are then referenced using label.histogram-1,
label.histogram-2, label.histogram-3...

MOMENTS

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.
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.
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.7

DFSCLUSTERING

Generated by Doxygen

274

Collective variables

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 [31] these matrices provide a representation of a graph and can thus can be analysed
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.

Compulsory keywords

MATRIX

the action that calcualtes the adjacency matrix vessel we would like to analyse

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

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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 [31].
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
Generated by Doxygen

5.6 Exploiting contact matrices

5.6.8

275

ROWSUMS

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
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

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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

Generated by Doxygen

276

Collective variables

Compulsory keywords

MAT←RIX

the action that calcualtes the adjacency matrix vessel we would like to analyse

Options

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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 is calculated
P
using
= − β1 log i exp (−βsi ) The value of β in this function is specified using (BE←TA= β ). 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

MIN

calculate the minimum value. To make this quantity continuous the minimum is calculated
β
using
=
The value of β in this function is specified using (BETA= β ) The
P
β

MAX

min

log

exp

max

= β log

exp

si
β

The value of β in this function is specified using (BETA=

MORE_THAN

BETWEEN

5.6 Exploiting contact matrices

277

HISTOGRAM

calculate a discretized histogram of the distribution of values. This shortcut allows you
to calculates NBIN quantites like BETWEEN. The final value can be referenced using label.histogram. You can use multiple instances of this keyword i.e. HISTOGRAM1, HISTOGR←AM2, HISTOGRAM3... 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 moment of a distriPN
1
m
bution 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.

Examples

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.

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.9

SPRINT

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:

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.
Generated by Doxygen

278

Collective variables

Description of components

Description

coord

all n sprint coordinates are calculated and then stored in increasing order. the smallest sprint coordinate will be labelled label.coord-1, the second smallest will be labelleled 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 refererred to elsewhere in the input file by using the label.vmean

vsum

VSUM

the norm of sum of vectors. The output component can be refererred to elsewhere
in the input file by using the label.vsum

spath

SPATH

the position on the path

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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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

sum

SUM

the sum of values

Compulsory keywords

MAT←RIX

the action that calcualtes the adjacency matrix vessel we would like to analyse

Generated by Doxygen

5.6 Exploiting contact matrices

279

Options

NOPBC

( default=off ) ignore the periodic boundary conditions when calculating distances

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

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:

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 foa a molecule composed of 7 hydrogen and 7 carbon
atoms. Once again two atoms are adjacent if they are within a cutoff:

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.10

CLUSTER_DIAMETER

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 analysing 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
Generated by Doxygen

280

Collective variables

the distances between the paris 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 parallelize

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.

5.6.11

CLUSTER_DISTRIBUTION

Generated by Doxygen

5.6 Exploiting contact matrices

281

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 [31].

Description of components

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

lessthan

LESS_THAN

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

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

Generated by Doxygen

( default=off ) calculate the derivatives for these quantities numerically

282

NOPBC

Collective variables

SERIAL

( default=off ) ignore the periodic boundary conditions when calculating distances
( default=off ) do the calculation in serial. Do not parallelize

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

LESS_THAN

BETWEEN

HISTOGRAM

ALT_MIN

MIN

MAX

min

log

exp

is calculated using

max = β log

exp

si
β

The value of β in this function is

Examples

Generated by Doxygen

5.6 Exploiting contact matrices

283

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 componets in this graph that contain more than 27 atoms is then computed. As discussed in
[31] this input was used to analyse the formation of a polycrystal of GeTe from amorphous GeTe.

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.12

CLUSTER_NATOMS

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 analysing 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

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 parallelize

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

284

Collective variables

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

5.6.13

CLUSTER_PROPERTIES

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 heterogenous nucleation
of a solute from a solvent) you might be interested in how many atoms are present in the largest cluster [31].

Description of components

Generated by Doxygen

5.6 Exploiting contact matrices

285

Quantity

Keyword

Description

vmean

VMEAN

the norm of the mean vector. The output component can be refererred to elsewhere in the input file by using the label.vmean

vsum

VSUM

the norm of sum of vectors. The output component can be refererred 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

highest

HIGHEST

the lowest of the quantitities calculated by this action

lessthan

LESS_THAN

lowest

LOWEST

the lowest of the quantitities 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 refererred 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

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.

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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

MEAN

Generated by Doxygen

286

Collective variables

MORE_THAN

LESS_THAN

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

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.

ALT_MIN

MIN

MAX

min

log

exp

is calculated using

max = β log

exp

si
β

The value of β in this function is

Generated by Doxygen

5.6 Exploiting contact matrices

287

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

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.14

OUTPUT_CLUSTER

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

Generated by Doxygen

288

Collective variables

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 reconstuct clusters

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.

Generated by Doxygen

Chapter 6

Analysis
PLUMED can be used to analyse trajectories either on the fly during an MD run or via postprocessing a trajectory
using driver. 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 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. This command can only be used when running an molecular dynamics trajectory - it cannot be used when analysing a trajectory using driver. As detailed in the documentation for COMMITTOR this command tells PLUMED (and the underlying MD code) to stop the calculation one some
criteria is satisified.
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 enseble 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 behavoir 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 cannonical ensemble at the appropriate
temperature.
REWEIGHT_BIAS

Calculate weights for ensemble averages that negate the effect the bias has on the
region of phase space explored

290

Analysis

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.

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 analysed 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.

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 5th 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).

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 analyse 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.

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:
Generated by Doxygen

6.2 COMMITTOR

291

• 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.1

Dimensionality Reduction

The remainder of the analysis tools within PLUMED allow one to do some form of dimensionality reduction as
detailed below.
CLASSICAL_MDS

Create a low-dimensional projection of a trajectory using the classical multidimensionalscaling algorithm.

PCA

Perform principal component analysis (PCA) using either the positions of the atoms a large
number of collective variables as input.

As with the grids described previously the STRIDE keyword tells PLUMED how frequently to collect data from the
trajectory. The RUN keyword then tells PLUMED how frequently to do the dimensionality reduction. As described
above if RUN is not present and you are analysing trajectories using driver all the data in the traejctory (with the
expection of the first frame) will be analysed.

6.2

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 analysed

Options

Generated by Doxygen

292

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 proceding 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 componets 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 torsions 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.

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.3

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 ouput
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

Generated by Doxygen

6.4 DUMPDERIVATIVES

ATOMS

293

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

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 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.

COM ATOMS=11-20 LABEL=c1
DUMPATOMS STRIDE=10 FILE=file.xyz ATOMS=1-10,c1

(see also COM)
The following input is very similar but dumps a .gro (gromacs) file, which also contains atom and residue names.

# 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

(see also COM and MOLINFO)

6.4

DUMPDERIVATIVES

Generated by Doxygen

294

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 proceding 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 componets 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.
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.5 DUMPFORCES

6.5

295

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 proceding 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 componets 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.
DISTANCE ATOM=1,2 LABEL=distance
DUMPFORCES ARG=distance STRIDE=1 FILE=forces

(See also DISTANCE)
Generated by Doxygen

296

6.6

Analysis

DUMPMASSCHARGE
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 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. .gro extension is automatically detected

Examples

You can add the DUMPMASSCHARGE action at the end of the plumed.dat file that you use during an MD
simulations:

c1: COM ATOMS=1-10
c2: COM ATOMS=11-20
PRINT ARG=c1,c2 FILE=colvar STRIDE=100
DUMPMASSCHARGE FILE=mcfile

(see also COM and PRINT)
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

With the following input you can dump only the charges for a specific group.

solute_ions: GROUP ATOMS=1-121,200-2012
DUMPATOMS FILE=traj.gro ATOMS=solute_ions STRIDE=100
DUMPMASSCHARGE FILE=mcfile ATOMS=solute_ions
Generated by Doxygen

6.7 DUMPMULTICOLVAR

297

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.7

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

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

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.
Generated by Doxygen

298

Analysis

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.8

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 proceding 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 componets 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

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
Generated by Doxygen

6.9 PRINT

299

x1: CENTER ATOMS=1-10
x2: CENTER ATOMS=11-20
d: DISTANCE ATOMS=x1,x2
DUMPPROJECTIONS ARG=d FILE=proj STRIDE=20

6.9

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.

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 proceding 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 componets 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...

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.
Generated by Doxygen

300

Analysis

DISTANCE ATOMS=2,5 LABEL=distance
ENERGY
LABEL=energy
PRINT ARG=distance
STRIDE=10
FILE=COLVAR
PRINT ARG=distance,energy
STRIDE=1000 FILE=COLVAR_ALL

(See also DISTANCE and ENERGY).

6.9.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 arrise 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

d1: DISTANCE ATOMS=1,10
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.10

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.
Generated by Doxygen

6.10 UPDATE_IF

301

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

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
proceding 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 componets 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.
solute: GROUP ATOMS=1-124
coord: COORDINATION GROUPA=solute GROUPB=500 R_0=0.5

Generated by Doxygen

302

Analysis

# 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

(See also GROUP, COORDINATION, and DUMPATOMS)

6.11

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 =

0
)
δ(s(x) − s0 ) exp + Vk(x,t
T
B

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

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.

x: DISTANCE ATOMS=1,2
RESTRAINT ARG=x SLOPE=1.0 AT=0.0
Generated by Doxygen

6.12 REWEIGHT_METAD

303

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.12

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 [33] 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

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.

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
Generated by Doxygen

304

Analysis

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.13

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 cannonical 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) =

h
0
)
δ(s(x) − s0 ) exp +( T11 − T12 U (x,t
kB
h
i

Pt
U (x,t0 )
1
1
t0 exp + T1 − T2
kB

The weights calculated by this action are equal to exp +(

1
T1

−

1
T2

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.
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 postprocessing.

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 postprocess 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
Generated by Doxygen

6.14 AVERAGE

305

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.

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.14

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 =

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 evalulated 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

Options

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

UNORMALIZED

( default=off ) output the unaveraged quantity/quantities.

LOGWEIGHTS

list of actions that calculates log weights that should be used to weight configurations when
calculating averages

Generated by Doxygen

306

ARG

Analysis

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 proceding 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 componets 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...

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.

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 aquired 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.

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 canononical ensemble at a temperature of 300 K.

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.15

HISTOGRAM
This is part of the analysis module

Generated by Doxygen

6.15 HISTOGRAM

307

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:

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 bandwith σ , 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 evalulated 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 tutorial Belfast tutorial: Analyzing CVs.

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 esimtation

KERNEL

( default=gaussian ) the kernel function you are using. More details on the kernels available in
plumed plumed can be found in kernelfunctions.

Generated by Doxygen

GRID_MIN

the lower bounds for the grid

GRID_MAX

the upper bounds for the grid

308

Analysis

Options

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

UNORMALIZED

( default=off ) output the unaveraged quantity/quantities.

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 proceding 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 componets 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...

DATA

input data from action with vessel and compute 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_UN←TIL

Only update this action until this time

Examples

The following input monitors two torsional angles during a simulation and outputs a continuos histogram as a function
of them at the end of the simulation.
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.
TORSION ATOMS=1,2,3,4 LABEL=r1
TORSION ATOMS=2,3,4,5 LABEL=r2
HISTOGRAM ...
ARG=r1,r2
USE_ALL_DATA
Generated by Doxygen

6.16 MULTICOLVARDENS

309

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.

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.

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.16

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 )
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.
Generated by Doxygen

310

Analysis

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

BANDWIDTH

the bandwidths for kernel density esimtation

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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

UNORMALIZED

( default=off ) output the unaveraged quantity/quantities.

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

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 specifes 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 specifes 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 specifes 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 specifes the upper bound for the region of the
y-axis that for which you are calculating the density/average

ZLOWER

this is required if you are using ZREDUCED. It specifes 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 specifes the upper bound for the region of the
z-axis that for which you are calculating the density/average

Generated by Doxygen

6.17 CONVERT_TO_FES

311

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 point on the grid and ouptuts this quantity to a file. In other words this input
P
instructs plumed to calculate ρ(r) = i K(r − ri )

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 analyse 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.

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.17

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

GRID
Options

Generated by Doxygen

the action that creates the input grid you would like to use

312

Analysis

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

COMPONENT

if your input is a vector field use this to specifiy 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 postprocessing 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

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.18

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
ensures that the grid is only output at the end of the trajectory

FILE

( default=density ) the file on which to write the grid.

Options

Generated by Doxygen

6.19 DUMPGRID

313

FMT

the format that should be used to output real numbers

COMPONENT

if your input is a vector field use this to specifiy the component of the input vector field for which
you wish to output

Examples

The input below can be used to postprocess 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.
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.19

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, whenver 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 beheath 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.
Compulsory keywords

Generated by Doxygen

314

Analysis

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.

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 the histogram accumulated thus
far every 100000 steps.
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
Generated by Doxygen

6.20 FIND_CONTOUR_SURFACE

315

6.20

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 calcualted 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
wher 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 countours 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

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

GRID

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

Generated by Doxygen

316

Analysis

Options

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

UNORMALIZED

( default=off ) output the unaveraged quantity/quantities.

LOGWEIGHTS

list of actions that calculates log weights that should be used to weight configurations when
calculating averages

COMPONENT

if your input is a vector field use this to specifiy the component of the input vector field for
which you wish to use

Examples

The input shown below was used to analyse 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
[34] 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.

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

6.21

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 calcualted 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.
Generated by Doxygen

6.21 FIND_CONTOUR

317

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

GRID

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

FILE

file on which to output coordinates

UNITS

( default=PLUMED ) the units in which to print out the coordinates. PLUMED means internal
PLUMED units
( 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

BUFFER

Options

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

UNORMALIZED

( default=off ) output the unaveraged quantity/quantities.

LOGWEIGHTS

list of actions that calculates log weights that should be used to weight configurations when
calculating averages

COMPONENT

if your input is a vector field use this to specifiy 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 [34]. The simulation
Generated by Doxygen

318

Analysis

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.

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.22

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 calcualted 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
wher 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
a set of equally spaced radii of a sphere that centered at on particular, user-speciified 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 =

√

1p
2i
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
Generated by Doxygen

6.22 FIND_SPHERICAL_CONTOUR

319

φ = (i + R, n)π(3 −

√

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 countours 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

GRID

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

FILE

file on which to output coordinates

UNITS

( default=PLUMED ) the units in which to print out the coordinates. PLUMED means internal
PLUMED units
the number of points for which we are looking for the contour

NPOINTS
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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

UNORMALIZED

( default=off ) output the unaveraged quantity/quantities.

LOGWEIGHTS

list of actions that calculates log weights that should be used to weight configurations when
calculating averages

COMPONENT

if your input is a vector field use this to specifiy the component of the input vector field for
which you wish to use

PRECISION

The number of digits in trajectory file

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 vapour. 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.
Generated by Doxygen

320

Analysis

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 teh droplet from the surrounding gas. The
value of the phase field on this isocontour is equal to 0.75.

# 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.23

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

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

Generated by Doxygen

6.24 INTERPOLATE_GRID

321

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
the action that creates the input grid you would like to use

GRID
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 parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

UNORMALIZED

( default=off ) output the unaveraged quantity/quantities.

LOGWEIGHTS

list of actions that calculates log weights that should be used to weight configurations when
calculating averages

COMPONENT

if your input is a vector field use this to specifiy 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).

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 ):
FOURIER_TRANSFORM STRIDE=1 GRID=density FT_TYPE=complex FOURIER_PARAMETERS=0,-1 FILE=fourier.dat

6.24

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

Generated by Doxygen

322

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

GRID

the action that creates the input grid you would like to use

Options

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

UNORMALIZED

( default=off ) output the unaveraged quantity/quantities.

LOGWEIGHTS

list of actions that calculates log weights that should be used to weight configurations when
calculating averages

COMPONENT

if your input is a vector field use this to specifiy 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 postprocess 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.

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.25

CLASSICAL_MDS
This is part of the analysis module

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
Generated by Doxygen

6.25 CLASSICAL_MDS

323

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 =

(Dij − dij )

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 analyse simulations can be found in the
tutorial Belfast tutorial: Adaptive variables II and in the following short video.

The atoms involved can be specified using

ATOMS

the atoms whose positions we are tracking for the purpose of analysing the data. 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

METRIC

( default=EUCLIDEAN ) how are we measuring the distances between configurations

RUN

( default=0 ) the frequency with which to run the analysis algorithm. The default value
of zero assumes you want to analyse the whole trajectory

LANDMARKS

( default=ALL ) only use a subset of the data that was collected. For more information on
the landmark selection algorithms that are available in plumed see landmarkselection.

NLOW_DIM

number of low-dimensional coordinates required

OUTPUT_FILE

file on which to output the final embedding coordinates

EMBEDDING_OFILE

( default=dont output ) file on which to output the embedding in plumed input format

Options

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

UNORMALIZED

( default=off ) output the unaveraged quantity/quantities.

WRITE_CHECKPOINT

( default=off ) write out a checkpoint so that the analysis can be restarted in a later
run

LOGWEIGHTS

list of actions that calculates log weights that should be used to weight configurations
when calculating averages

Generated by Doxygen

324

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 proceding 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 componets 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 PL←UMED with the appropriate flag. You can use multiple instances of this keyword i.e.
ARG1, ARG2, ARG3...

FMT

the format that should be used in analysis output files

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 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.

CLASSICAL_MDS ...
ATOMS=1-256
METRIC=OPTIMAL-FAST
USE_ALL_DATA
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.25.1

Method of optimisation

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α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:
Generated by Doxygen

6.25 CLASSICAL_MDS

325


0 d212 d213
D2 (X) =  d212 0 d223 
d213 d223 0



1 2
1 2
1 2
1 2
2 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α1 Xα3
(Xα )

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:

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 minimise the stress. If you use an interative 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.
Generated by Doxygen


Xα1 Xα3
Xα2 Xα3 
Xα3 Xα3

326

6.26

Analysis

PCA
This is part of the analysis module

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
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
analysed 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.

The atoms involved can be specified using

ATOMS

the atoms whose positions we are tracking for the purpose of analysing the data. 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

METRIC

( default=EUCLIDEAN ) how are we measuring the distances between configurations

RUN

( default=0 ) the frequency with which to run the analysis algorithm. The default value of zero
assumes you want to analyse the whole trajectory

Generated by Doxygen

6.26 PCA

327

NLOW_DIM

number of PCA coordinates required

OFILE

the file on which to output the eigenvectors

Options

SERIAL

( default=off ) do the calculation in serial. Do not parallelize

LOWMEM

( default=off ) lower the memory requirements

TIMINGS

( default=off ) output information on the timings of the various parts of the calculation

UNORMALIZED

( default=off ) output the unaveraged quantity/quantities.

WRITE_CHECKPOINT

( default=off ) write out a checkpoint so that the analysis can be restarted in a later
run

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 proceding 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 componets 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 PL←UMED with the appropriate flag. You can use multiple instances of this keyword i.e.
ARG1, ARG2, ARG3...

FMT

the format that should be used in analysis output files

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 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.

PCA METRIC=OPTIMAL ATOMS=1-22 STRIDE=1 USE_ALL_DATA 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 chnages in the six distances seen in the previous lines. Notice that here the TYPE=EUCLID←EAN keyword is used to indicate that no alighment 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
Generated by Doxygen

328

Analysis

1000 steps. Consequently, if you run a 2000 step simulation the PCA analysis will be performed twice. The REWE←IGHT_BIAS keyword in this input tells PLUMED that rather that ascribing a weight of one to each of the frames when
calculating averages and covariances 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).

d1:
d2:
d3:
d4:
d5:
d6:

DISTANCE
DISTANCE
DISTANCE
DISTANCE
DISTANCE
DISTANCE

ATOMS=1,2
ATOMS=1,3
ATOMS=1,4
ATOMS=2,3
ATOMS=2,4
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

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.

METAD

Used to performed MetaDynamics on one or more collective variables.

METAINFERENCE

Calculate the Metainference Score for a set of back calculated experimental data.

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.

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 [35] [36] [37]. The biasing potential in this method is as follows:

V (ρ(t)) =
where

K
2

(ρ(t) − ρm (t)) ,

ρ(t) > ρm (t)
ρ(t) ≤ ρm (t),

330

Bias

ρ(t) = (CV (t) − T O)

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

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 will be refereceable 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).

Compulsory keywords

The array of target values

KAPPA

The array of force constants.

Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

ARG

Generated by Doxygen

7.2 BIASVALUE

331

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.

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

(See also DISTANCE and PRINT).

7.2

BIASVALUE
This is part of the bias module

Takes the value of one variable and use it as a 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

Description

bias

the instantaneous value of the bias potential

_bias

one or multiple instances of this quantity will be refereceable 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

Generated by Doxygen

( default=off ) calculate the derivatives for these quantities numerically

332

ARG

Bias

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

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

(See also DISTANCE and PRINT).

Another thing one can do is asking one system to follow a circle in sin/cos according a time dependence

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

(see also TIME, MATHEVAL, COM, DISTANCE, and PRINT).
Generated by Doxygen

7.3 EXTENDED_LAGRANGIAN

7.3

333

EXTENDED_LAGRANGIAN

Add extended Lagrangian.
This action can be used to create fictitious collective variables coupled to the real ones. Given xi the i-th argument
of this bias potential, potential and kinetic contributions are added to the energy of the system as

V =

X ki
i

(xi − si )2 +

X ṡ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 [38]
. 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 [39] [40] . 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

Description

bias

the instantaneous value of the bias potential

_fict

_vfict

Generated by Doxygen

334

Bias

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

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.
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

(See also TORSION, METAD, and PRINT).
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
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

(See also TORSION and PRINT)
Generated by Doxygen

7.4 EXTERNAL

7.4

335

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

Description

bias

the instantaneous value of the bias potential

Compulsory keywords

FILE

the name of the file containing the external potential.

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

ARG

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.
Generated by Doxygen

336

Bias

DISTANCE ATOMS=3,5 LABEL=d1
EXTERNAL ARG=d1 FILE=bias.dat LABEL=external

(See also DISTANCE PRINT).
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. If you run with NOSPLINE you do not need to provide derivative information.
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:

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 untill you get to the 100th 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.

7.5

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:
Generated by Doxygen

7.5 LOWER_WALLS

337

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

Description

bias

the instantaneous value of the bias potential

force2

the instantaneous value of the squared force due to this bias potential

Compulsory keywords

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

ARG

Examples

The following input tells plumed to add both a lower and an upper walls on the distance between atoms 3 and 5 and
Generated by Doxygen

338

Bias

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.

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

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 [41].

V (~s, t) =

• It works only for one-dimensional biases;
• It works both with and without GRID;
• The interval limit sw in a region where the free energy derivative is not large;
• If in the region outside the limit sw the system has a free energy minimum, the INTERVAL keyword should be
used together with a UPPER_WALLS or LOWER_WALLS at sw.

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 [46] 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 using Eq. 12 in Eq. 3 in [3] and 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-ct) which can be used to obtain a reweighted histogram. The calculation of c(t)
is enabled by using the keyword REWEIGHTING_NGRID where the grid used for the calculation is specified. This
grid should have a size that is equal or larger than the grid given in GRID_BIN./ By default c(t) is updated every
50 Gaussian hills but this can be changed by using the REWEIGHTING_NHILLS keyword. This option can only be
employed together with Well-Tempered Metadynamics and requires that a grid is used.
Additional material and examples can be also found in the tutorials:

• Belfast tutorial: Metadynamics
• Belfast tutorial: Replica exchange I
• Belfast tutorial: Replica exchange II and Multiple walkers
Generated by Doxygen

340

Bias

Notice that at variance with PLUMED 1.3 it is now straightforward to apply concurrent metadynamics as done e.g.
in Ref. [47] . This indeed can be obtained by using the METAD action multiple times in the same input file.

Description of components

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

REWEIGHTING_NGRID

the instantaneous value of the bias normalized using the c(t) reweighting factor [rbias=bias-c(t)].This component can be used to obtain a
reweighted histogram.

rct

REWEIGHTING_NGRID

the reweighting factor c(t).

acc

ACCELERATION

the metadynamics acceleration factor

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

GRID_SPARSE

( default=off ) use a sparse grid to store hills

GRID_NOSPLINE

( default=off ) don't use spline interpolation with grids

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
other WALKERS_∗ options

ACCELERATION

( default=off ) Set to TRUE if you want to compute the metadynamics acceleration factor.

Generated by Doxygen

7.6 METAD

341

ARG

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 biasfactor. Please note you
must also specify temp

DAMPFACTOR

damp hills with exp(-max(V)/(kbT∗DAMPFACTOR)

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∗DeltaT∗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)

REWEIGHTING_NGRID

calculate the c(t) reweighting factor and use that to obtain the normalized bias
[rbias=bias-c(t)].Here you should specify the number of grid points required in
each dimension.The number of grid points should be equal or larger to the
number of grid points given in GRID_BIN.This method is not compatible with
metadynamics not on a grid.

REWEIGHTING_NHILLS

how many Gaussian hills should be deposited between calculating the c(t)
reweighting factor.The default is to do this every 50 hills.

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 timestep 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

monodimensional 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
allows per-action setting of restart (YES/NO/AUTO)

SIGMA_MIN
RESTART

Generated by Doxygen

342

Bias

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.
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 Gaussians, with diffusion scheme where you use a Gaussian that should cover the space
of 20 timesteps in collective variables. Note that in this case the histogram correction is needed when summing
up hills.
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 Gaussians, 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.
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 Gaussians you might want to limit how the hills width can change. You can use SIG←MA_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.
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 [46] 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
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
Generated by Doxygen

7.6 METAD

343

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 REWEIGHTING_NGRID where the grid used for the calculation is set.
The number of grid points given in REWEIGHTING_NGRID should be equal or larger than the number of grid
points given in GRID_BIN.
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
REWEIGHTING_NGRID=150,150
REWEIGHTING_NHILLS=20
... METAD

Here we have asked that the calculation is performed every 20 hills by using REWEIGHTING_NHILLS keyword.
If this keyword is not given the calculation will by default be performed every 50 hills. 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-c(t)] which can be used to obtain a reweighted
histogram or free energy surface using the HISTOGRAM analysis.

The kinetics of the transitions between basins can also be analysed on the fly as in [48]. The flag ACCEL←ERATION 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.

You can also provide a target distribution using the keyword TARGET [49] [50] [51] The TARGET should be a
grid containing a free-energy (i.e. the -kbT∗log of the desired target distribution). Gaussians 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 [51] This choice allows to avoid exceedingly large Gaussians 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 [52] Alternatively, if you use a BIASFACTOR yout 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.
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

344

7.7

Bias

METAINFERENCE
This is part of the bias module

Calculate the Metainference Score for a set of back calculated experimental data.
The back calculated data, that are expected to be averages over replicas (NR=1,2,..,N) The functional form of this
bias can be chosen between three variants selected with NOISE=GAUSS,MGAUSS,OUTLIERS which correspond
to modelling the noise for the arguments as a single gaussian common to all the data points, a gaussian per data
point or a single long-tailed gaussian common to all the data points.
As from Metainference theory there are two sigma values: SIGMA_MEAN represent the error of calculating an
average quanity 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. 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.

Description of components

Description

bias

the instantaneous value of the bias potential

sigma

uncertainty parameter

scale

scale parameter

MC acceptance

Compulsory keywords

NOISETYPE

functional form of the noise (GAUSS,MGAUSS,OUTLIERS)

SCALE0

initial value of the uncertainty parameter

SCALE_MIN

minimum value of the uncertainty parameter

SCALE_MAX

maximum value of the uncertainty parameter

DSCALE

maximum MC move of the uncertainty parameter

SIGMA0

initial value of the uncertainty parameter

SIGMA_MIN

minimum value of the uncertainty parameter

SIGMA_MAX

maximum value of the uncertainty parameter

DSIGMA

maximum MC move of the uncertainty parameter

SIGMA_MEAN

starting value for the uncertainty in the mean estimate

Options

Generated by Doxygen

7.7 METAINFERENCE

345

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

SCALEDATA

( default=off ) Set to TRUE if you want to sample a scaling factor common to all
values and replicas

ARG

PARARG

reference values for the experimental data, these can be provided as arguments without derivatives
reference values for the experimental data

PARAMETERS
TEMP

the system temperature - this is only needed if code doesnt' pass the temperature to plumed

MC_STEPS

number of MC steps

MC_STRIDE

MC stride

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

RDC ...
LABEL=rdc
SCALE=0.0001
GYROM=-72.5388
ATOMS1=22,23
ATOMS2=25,27
ATOMS3=29,31
ATOMS4=33,34
... RDC
ardc: ENSEMBLE ARG=rdc.*
METAINFERENCE ...
ARG=ardc.*
NOISETYPE=MGAUSS
PARAMETERS=1.9190,2.9190,3.9190,4.9190
SCALEDATA SCALE0=1 SCALE_MIN=0.00001 SCALE_MAX=3 DSCALE=0.00
SIGMA0=0.01 SIGMA_MIN=0.00001 SIGMA_MAX=3 DSIGMA=0.00
SIGMA_MEAN=0.001
TEMP=300
LABEL=spe
... METAINFERENCE
PRINT ARG=spe.bias FILE=BIAS STRIDE=1
Generated by Doxygen

346

Bias

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.

METAINFERENCE ...
ARG=ardc.*
NOISETYPE=OUTLIERS
PARAMETERS=1.9190,2.9190,3.9190,4.9190
SCALEDATA SCALE0=1 SCALE_MIN=0.00001 SCALE_MAX=3 DSCALE=0.00
SIGMA0=0.01 SIGMA_MIN=0.00001 SIGMA_MAX=3 DSIGMA=0.00
SIGMA_MEAN=0.001
TEMP=300
LABEL=spe
... METAINFERENCE

(See also RDC and ENSEMBLE).

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 [53] and Jarzynski sampling [54].
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. Inbetween
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

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 will be refereceable 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 will be refereceable 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.
Generated by Doxygen
one or multiple instances of this quantity will be refereceable 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

7.8 MOVINGRESTRAINT

347

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 STEPx with x=0,1,2,...,n. Each value given represents the
MD step at which the restraint parameters take the values KAPPAx and ATx. You can use multiple
instances of this keyword i.e. STEP1, STEP2, STEP3...

ATx is equal to the position of the restraint at time STEPx. For intermediate times this parameter is
linearly interpolated. If no ATx is specified for STEPx then the values of AT are kept constant during
the interval of time between STEPx-1 and STEPx. You can use multiple instances of this keyword i.e.
AT1, AT2, AT3...

KAPPA

KAPPAx is equal to the value of the force constants at time STEPx. For intermediate times this
parameter is linearly interpolated. If no KAPPAx is specified for STEPx then the values of KAPPAx
are kept constant during the interval of time between STEPx-1 and STEPx. 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

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.
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.
Generated by Doxygen

348

Bias

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

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) [55], a version of MetaDynamics [41] in which multiple
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)

V (si , t) =

X
kτ sw, the history dependent potential is still updated according to the above equations but the metadynamics
force is set to zero for s < sw. Notice that Gaussians are added also if s < sw, as the tails of these Gaussians
influence VG in the relevant region s > sw. In this way, the force on the system in the region s > sw comes from
both metadynamics and the force field, in the region s < sw 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 sw in a region where the free energy derivative is not large;
• If in the region outside the limit sw the system has a free energy minimum, the INTERVAL keyword should be
used together with a UPPER_WALLS or LOWER_WALLS at sw.
Multiple walkers [46] can also be used, in the MPI implementation only. See below the examples.
Description of components

Generated by Doxygen

350

Bias

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

MULTIPLE_WALKERS

( default=off ) Switch on MPI version of multiple walkers

ARG

FILE
HEIGHT

files in which the lists of added hills are stored
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 biasfactor, 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∗DeltaT∗pace∗timestep)/tau

GRID_RFILES

read grid for the bias

GRID_WFILES

dump grid for the bias

GRID_WSTRIDE

frequency for dumping the grid

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.10 RESTRAINT

351

INTERVAL_MIN

monodimensional lower limits, outside the limits the system will not feel the
biasing force.

INTERVAL_MAX

monodimensional upper limits, outside the limits the system will not feel the
biasing force.

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 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.

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).

If you use well-tempered metadynamics, you should specify a single biasfactor and initial Gaussian height.
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

Only the MPI version of multiple-walkers is currently implemented.
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
MULTIPLE_WALKERS
... PBMETAD
PRINT ARG=d1,d2,pb.bias STRIDE=100 FILE=COLVAR

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.
Generated by Doxygen

352

Bias

The resulting potential is given by:

X ki
i

(xi − ai )2 + mi ∗ (xi − ai )

.
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

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

Generated by Doxygen

7.11 UPPER_WALLS

353

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

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

(See also DISTANCE and PRINT).

7.11

UPPER_WALLS
This is part of the bias module

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

Description

bias

the instantaneous value of the bias potential

force2

the instantaneous value of the squared force due to this bias potential

Compulsory keywords

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

Generated by Doxygen

354

Bias

Options

NUMERICAL_DERIVATIVES

( default=off ) calculate the derivatives for these quantities numerically

ARG

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.

(See also DISTANCE and PRINT).

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.

Generated by Doxygen

7.12 RESTART

355

Attention
This directive can have also other side effects, e.g. on METAD and PBMETAD and on some analysis action.

Options

( default=off ) switch off restart - can be used to override the behavior of the MD engine

Examples

Using the following input:

d: DISTANCE ATOMS=1,2
PRINT ARG=d FILE=out

(See also DISTANCE and PRINT). 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:

RESTART
d: DISTANCE ATOMS=1,2
PRINT ARG=d FILE=out

the file 'out' will be appended. (See also DISTANCE and PRINT).
In the following case, file out1 will be backed up and file out2 will be concatenated

RESTART
d1: DISTANCE
d2: DISTANCE
PRINT ARG=d1
PRINT ARG=d2

ATOMS=1,2
ATOMS=1,2
FILE=out1 RESTART=NO
FILE=out2

(See also DISTANCE and PRINT).

Generated by Doxygen

356

Bias

Generated by Doxygen

Chapter 8

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.
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 variousactions

info

This tool allows you to obtain information about your plumed version

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

simplemd

simplemd allows one to do molecular dynamics on systems of Lennard-Jones atoms.

sum_hills

sum_hills is a tool that allows one to to use plumed to post-process an existing hills/colvar file

For all these tools and to use PLUMED as a plugin in an MD calculation you will need an input file.

8.1

driver-float
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

358

Command Line Tools

--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

--dump-full-virial

( default=off ) with –dump-forces, it dumps the 9 components of the virial

--length-units
--mass-units
--charge-units
--dump-forces
--dump-forces-fmt
--pdb
--mc
--box
--natoms

units for length, either as a string or a number

--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

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
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 orthorombic, 9 for generic)
provides number of atoms - only used if file format does not contain number of
atoms
output a file containing the forces due to the bias evaluated using numerical
derivatives and using the analytical derivatives implemented in plumed

Generated by Doxygen

8.2 driver

359

Examples

plumed driver-float --plumed plumed.dat --ixyz trajectory.xyz

Manual

Navigation menu

Versions of this User Manual:

Views

Navigation