Skip to content
Snippets Groups Projects
Commit 11135dd5 authored by Carlo Camilloni's avatar Carlo Camilloni
Browse files

Manual: syntax

parent 22fd8b1e
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
user-doc/Doxyfile
+ 1
− 0
View file @ 11135dd5
...@@ -737,6 +737,7 @@ INPUT = IntroPP.txt \ ...@@ -737,6 +737,7 @@ INPUT = IntroPP.txt \
BiasPP.txt \ BiasPP.txt \
AnalysisPP.txt \ AnalysisPP.txt \
ColvarPP.txt \ ColvarPP.txt \
SyntaxPP.txt \
FunctionsPP.txt \ FunctionsPP.txt \
GroupPP.txt \ GroupPP.txt \
InstallationPP.txt \ InstallationPP.txt \
......
user-doc/Intro.txt
+ 1
− 153
View file @ 11135dd5
...@@ -50,160 +50,8 @@ The following is a list of the various standalone tools that PLUMED contains. ...@@ -50,160 +50,8 @@ The following is a list of the various standalone tools that PLUMED contains.
@TOOLS@ @TOOLS@
For all these tools and to use PLUMED as a plugin in an MD calculation you will need an input file. Within For all these tools and to use PLUMED as a plugin in an MD calculation you will need an input file.
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). 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}).
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:
\verbatim
DISTANCE ATOMS=1,2
\endverbatim
(see \ref DISTANCE)
Then PLUMED will do nothing other than read in your input file. In contrast if you do:
\verbatim
DISTANCE ATOMS=1,2 LABEL=d1
PRINT ARG=d1 FILE=colvar STRIDE=10
\endverbatim
(see \ref 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:
\verbatim
d1: DISTANCE ATOMS=1,2
PRINT ARG=d1 FILE=colvar STRIDE=10
\endverbatim
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 \ref Regex). For this you need to compile PLUMED with the appropriate flag.
\section Units A note on 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
\ref UNITS keyword.
Those are the essentials but there are a few other tricks that we didn't know where else to put in the manual so we stuck them here.
\section comments Comments
If you are an organised sort of person who likes to remember what the hell you were trying to do when you ran a
particular simulation you might find it useful to put comments in your input file. In PLUMED you can do this as
comments can be added using a # sign. On any given line everything after the # sign is ignored so
erm... yes add lines of comments or trailing comments to your hearts content as shown below (using Shakespeare is optional):
\verbatim
# This is the distance between two atoms:
DISTANCE ATOM=1,2 LABEL=d1
UPPER_WALLS ARG=d1 AT=3.0 KAPPA=3.0 LABEL=Snout # In this same interlude it doth befall. That I, one Snout by name, present a wall.
\endverbatim
(see \ref DISTANCE and \ref UPPER_WALLS)
An alternative to including comments in this way is to use line starting ENDPLUMED. Everything in the PLUMED input after this
keyword will be ignored.
\section ContinuationLines Continuation lines
If your input lines get very long then editing them using vi and other such text editors becomes a massive pain in the arse.
We at PLUMED are aware of this fact and thus have provided a way of doing line continuations so as to make your life that much
easier - aren't we kind? Well no not really, we have to use this code too. Anyway, you can do continuations by using the "..." syntax
as this makes this:
\verbatim
DISTANCES ATOMS1=1,300 ATOMS2=1,400 ATOMS3=1,500
\endverbatim
(see \ref DISTANCES)
equivalent to this:
\verbatim
DISTANCES ...
# we can also insert comments here
ATOMS1=1,300
# multiple kewords per line are allowed
ATOMS2=1,400 ATOMS3=1,500
#empty lines are also allowed
... DISTANCES
\endverbatim
\section includes Including other files in the PLUMED input
If, for some reason, you want to spread your PLUMED input over a number of files you can use \ref INCLUDE as shown below:
\verbatim
INCLUDE FILE=filename
\endverbatim
So, for example, a single "plumed.dat" file:
\verbatim
DISTANCE ATOMS=0,1 LABEL=dist
RESTRAINT ARG=dist
\endverbatim
(see \ref DISTANCE and \ref RESTRAINT)
could be split up into two files as shown below:
\verbatim
DISTANCE ATOMS=0,1 LABEL=dist
INCLUDE FILE=toBeIncluded.dat
\endverbatim
plus a "toBeIncluded.dat" file
\verbatim
RESTRAINT ARG=dist
\endverbatim
However, when you do this it is important to recognise that \ref INCLUDE is a real directive that is only resolved
after all the \ref comments have been stripped and the \ref ContinuationLines have been unrolled. This means it
is not possible to do things like:
\verbatim
# this is wrong:
DISTANCE INCLUDE FILE=options.dat
RESTRAINT ARG=dist
\endverbatim
\section load Loading shared libraries
You can introduce new functionality into PLUMED by placing it directly into the src directory and recompiling the
PLUMED libraries. Alternatively, if you want to keep your code independent from the rest of PLUMED (perhaps
so you can release it independely - we won't be offended), then you can create your own dynamic library. To use this
in conjuction with PLUMED you can then load it at runtime by using the \ref LOAD keyword as shown below:
\verbatim
LOAD FILE=library.so
\endverbatim
N.B. If your system uses a different suffix for dynamic libraries (e.g. macs use .dylib) then PLUMED will try to
automatically adjust the suffix accordingly.
\section degub Debugging the code
The \ref DEBUG action provides some functionality for debugging the code that may be useful if you are doing
very intensive development of the code of if you are running on a computer with a strange architecture.
*/ */
user-doc/Syntax.txt 0 → 100644
+ 175
− 0
View file @ 11135dd5
/**
\page Syntax Syntax
To run PLUMED 2 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 <a href="http://www.youtube.com/watch?v=PxJP16qNCYs"> 10-minute video </a>.
More information on the input syntax as well as details on the the various trajectory
analsyis tools that come with PLUMED are given in:
- \ref Colvar tells you about the functions of the positions atoms that PLUMED can calculate.
- \ref Function tells you about the functions of collective variables that PLUMED can calculate.
- \ref Analysis tells you about the various forms of analysis you can run on trajectories using PLUMED.
- \ref Bias tells you about the methods that you can use to bias molecular dynamics simulations with PLUMED.
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). 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}).
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:
\verbatim
DISTANCE ATOMS=1,2
\endverbatim
(see \ref DISTANCE)
Then PLUMED will do nothing other than read in your input file. In contrast if you do:
\verbatim
DISTANCE ATOMS=1,2 LABEL=d1
PRINT ARG=d1 FILE=colvar STRIDE=10
\endverbatim
(see \ref 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:
\verbatim
d1: DISTANCE ATOMS=1,2
PRINT ARG=d1 FILE=colvar STRIDE=10
\endverbatim
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 \ref Regex). For this you need to compile PLUMED with the appropriate flag.
\section Units A note on 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
\ref UNITS keyword.
Those are the essentials but there are a few other tricks that we didn't know where else to put in the manual so we stuck them here.
\section comments Comments
If you are an organised sort of person who likes to remember what the hell you were trying to do when you ran a
particular simulation you might find it useful to put comments in your input file. In PLUMED you can do this as
comments can be added using a # sign. On any given line everything after the # sign is ignored so
erm... yes add lines of comments or trailing comments to your hearts content as shown below (using Shakespeare is optional):
\verbatim
# This is the distance between two atoms:
DISTANCE ATOM=1,2 LABEL=d1
UPPER_WALLS ARG=d1 AT=3.0 KAPPA=3.0 LABEL=Snout # In this same interlude it doth befall. That I, one Snout by name, present a wall.
\endverbatim
(see \ref DISTANCE and \ref UPPER_WALLS)
An alternative to including comments in this way is to use line starting ENDPLUMED. Everything in the PLUMED input after this
keyword will be ignored.
\section ContinuationLines Continuation lines
If your input lines get very long then editing them using vi and other such text editors becomes a massive pain in the arse.
We at PLUMED are aware of this fact and thus have provided a way of doing line continuations so as to make your life that much
easier - aren't we kind? Well no not really, we have to use this code too. Anyway, you can do continuations by using the "..." syntax
as this makes this:
\verbatim
DISTANCES ATOMS1=1,300 ATOMS2=1,400 ATOMS3=1,500
\endverbatim
(see \ref DISTANCES)
equivalent to this:
\verbatim
DISTANCES ...
# we can also insert comments here
ATOMS1=1,300
# multiple kewords per line are allowed
ATOMS2=1,400 ATOMS3=1,500
#empty lines are also allowed
... DISTANCES
\endverbatim
\section includes Including other files in the PLUMED input
If, for some reason, you want to spread your PLUMED input over a number of files you can use \ref INCLUDE as shown below:
\verbatim
INCLUDE FILE=filename
\endverbatim
So, for example, a single "plumed.dat" file:
\verbatim
DISTANCE ATOMS=0,1 LABEL=dist
RESTRAINT ARG=dist
\endverbatim
(see \ref DISTANCE and \ref RESTRAINT)
could be split up into two files as shown below:
\verbatim
DISTANCE ATOMS=0,1 LABEL=dist
INCLUDE FILE=toBeIncluded.dat
\endverbatim
plus a "toBeIncluded.dat" file
\verbatim
RESTRAINT ARG=dist
\endverbatim
However, when you do this it is important to recognise that \ref INCLUDE is a real directive that is only resolved
after all the \ref comments have been stripped and the \ref ContinuationLines have been unrolled. This means it
is not possible to do things like:
\verbatim
# this is wrong:
DISTANCE INCLUDE FILE=options.dat
RESTRAINT ARG=dist
\endverbatim
\section load Loading shared libraries
You can introduce new functionality into PLUMED by placing it directly into the src directory and recompiling the
PLUMED libraries. Alternatively, if you want to keep your code independent from the rest of PLUMED (perhaps
so you can release it independely - we won't be offended), then you can create your own dynamic library. To use this
in conjuction with PLUMED you can then load it at runtime by using the \ref LOAD keyword as shown below:
\verbatim
LOAD FILE=library.so
\endverbatim
N.B. If your system uses a different suffix for dynamic libraries (e.g. macs use .dylib) then PLUMED will try to
automatically adjust the suffix accordingly.
\section degub Debugging the code
The \ref DEBUG action provides some functionality for debugging the code that may be useful if you are doing
very intensive development of the code of if you are running on a computer with a strange architecture.
*/
user-doc/extract
+ 1
− 1
View file @ 11135dd5
...@@ -213,7 +213,7 @@ do ...@@ -213,7 +213,7 @@ do
fi fi
done done
for file in Bias Colvar Functions Group Installation Intro Analysis Glossary Tutorials Modules Regex for file in Bias Syntax Colvar Functions Group Installation Intro Analysis Glossary Tutorials Modules Regex
do do
cat $file.txt | cat $file.txt |
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment