forked from plumed/plumed2
/
usingDoxygen.txt
375 lines (280 loc) · 18.4 KB
/
usingDoxygen.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
// This document is formatted for Doxygen
/**
\page usingDoxygen Creating plumed documentation
To create the plumed manual you should go to the <b> user-doc </b> directory and type <b> make </b>.
This command works because user documentation for all the PLMD::Action is inside the source code. If
you look at the documentation page for any of the actions that are implemented in plumed you will
see that it is composed of three pars:
- A short introduction which describes what the method does.
- A description of the various keywords for the calculation.
- An example/some examples of how the PLMD::Action can be used.
Furthermore, you will also have noticed that if you make an error in the input for any PLMD::Action the
descriptions of all the keywords from the manual appears in the log file. This is possible because manual
pages for PLMD::Action are inside the code and because the manual is created using the
following packages:
- Doxygen: http://www.doxygen.org
- Graphviz: http://www.graphviz.org/
In addition a special class, PLMD::Keywords, is used to store the descriptions of the syntax for any given
action so that this data can be produced in the output when the user makes a mistake in input. In the following
a step-by-step explanaition as to how to use the documentation prodcuing functionality of plumed is provided. When
you have finished creating your new documentation they should be incorporated automatically in the manual the next
time you make the manual. Furthermore, a number of checks of your manual are performed when you make the manual
so any errors should be straightforward to find.
\section registerkeys Registering Keywords
When you implement any new PLMD::Action in plumed you must first create the documentation for the keywords that you
will use to read the input for your new method. In fact you cannot read in undocumented keywords using plumed. The
documentation for keywords is created in a static method of the action called registerKeywords. This method
should be declared in the definition of the class as follows:
\verbatim
static void registerKeywords(Keywords& keys);
\endverbatim
The static atribute allows one to use the registerKeywords routine when no instances of the class have been created.
This is essential as keywordRegistration in plumed is done before the list of PLMD::Action is created. This means
that when the keywords are created plumed has no understanding of the hierachy of inherited Actions. Hence, before
adding your own Keywords you must ensure that the keywords for the class from which your new class inherits have been
added. In pracise this is done by calling PLMD::Colvar::registerKeywords, PLMD::function::Function::registerKeywords or
PLMD::Bias::registerKeywords for a new PLMD::Colvar, PLMD::function::Function or PLMD::bias::Bias respectively. To be clear these
functions will ensure that generic keywords such as LABEL, NUMERICAL_DERIVATIVES or ARG are registered and explained in the
manual. If your method requires the derivatives of some value and you have no way of implementing the analytical derivatives
you should also call PLMD::ActionWithValue::noAnalyticalDerivatives. This routine will ensure that plumed's numerical
derivatives routines are used to calculation your derivatives automatically and will ensure that a message is put in the plumed
manual so that other users are aware that numerical derivatives are being used.
Once you have called the reigsterKeywords routine for the PLMD::Action above yours in the hierachy you can begin to add
the keywords for your new method. These keywords will have one of 5 attributes:
<table align=center frame=void width=95%% cellpadding=5%%>
<tr>
<td width=5%%> <b> compulsory </b> </td> <td> These are the quantities that must be defined in order to perform your action </td>
</tr> <tr>
<td> <b> optional </b> </td> <td> If there is some alternate way of performing your calculation that requires numerical input you should declare your keyword as optional </td>
</tr> <tr>
<td> <b> flag </b> </td> <td> This is used to declare keywords such as NOPBC that tell plumed to turn on/off some feature of the calculation </td>
</tr> <tr>
<td> <b> atoms </b> </td> <td> If you are reading a list of atoms after the keyword then you should use this keyword. You can easily specify if there are multiple ways of defining the atoms involved in the action in the manual. To register the keywords for this first method of specifying the atoms using atoms-1. Then register the keywords for the second way of specifying the atoms using atoms-2 and so on. A manual that states that these keywords can be used in an either or fashion, much that for <a href="../../user-doc/html/_t_o_r_s_i_o_n.html"> TORSION </a>, will then be generated. </td>
</tr> <tr>
<td> <b> numbered </b> </td> <td> If you need to read in a list of similar keywords such as keyword0, keyword1, keyword2... then you must use this option. These keywords will be assumed to be optional. However, you can set them to be atoms or whatever by using reset_style(keyword,newstyle). </td>
</table>
All keywords (other than flags) are added using the add method of PLMD::Keywords. This command has the following syntax:
\verbatim
keys.add( attribute, keyword, explanation );
\endverbatim
where <i> attribute </i> is one of the options from the above table, <i> keyword </i> is the word that appears on the input line and <i> explanation </i> is an explantion
of what the keyword does. If your keyword is compulsory it can also be added using:
\verbatim
keys.add( attribute, keyword, default, explanation );
\endverbatim
where <i> default </i> is a string containing the default value to use for the quantity.
Flags are added using the add flag method, this has syntax:
\verbatim
keys.addFlag( keyword, default, explantion );
\endverbatim
where default is a bool that tells plumed if by default this option is/is not in use.
\section reading Reading the input keywords
Keywords are read in using either PLMD::Action::parse, PLMD::Action::parseVector, PLMD::Action::parseNumberedVector or PLMD::Action::parseFlag.
These routines will use the information provided during keyword registration to check the sanity of any input. For instance if you declare a
compulsory keyword and do not specify a default value then the code will automatically complain if the particular keyword is missing from input.
In addition, if the vector you pass to PLMD::Action::parseVector and PLMD::Action::parseNumberedVector has a
size greater than 0 plumed will assume that the input should contain a vector of this size and will complain if it finds a different sized vector.
\section components Registering components
In plumed 2.1 we will also begin registering all the components that are calculated by your action.
In plumed 2.2 registering components will become compulsory and your features will not work if this is not done.
This registering of components means that in the registerKeywords method for commands such as:
\verbatim
d1: DISTANCE COMPONENTS
\endverbatim
which calculates quantities that can be referenced in the input as d1.x, d1.y and d1.z, you will have to provide
documentation for the manual that describes what information is stored in the x, y and z components. As an example
for the distances components this documenation takes the following form:
\verbatim
keys.addOutputComponent("x","COMPONENTS","the x-component of the vector connecting the two atoms");
keys.addOutputComponent("y","COMPONENTS","the y-component of the vector connecting the two atoms");
keys.addOutputComponent("z","COMPONENTS","the z-component of the vector connecting the two atoms");
\endverbatim
As you can see this new feature works in a similar manner to the feature by which the keywords are registered. Both
these features serve to keep the manual up to date with only a relatively small amount of effort on the part of the
developer.
All components registered by plumed should be added using a variant of the addOutputComponent method of PLMD::Keywords.
This command has the following syntax:
\verbatim
keys.addOutputComponent( name, keyword, explanation )
\endverbatim
where <i> name </i> is the name the component will be given i.e. the quantity will be referencable in input as <i> label.name </i>.
<i> keyword </i> is the name of any keyword that must be added to the input for the action in order to calculate this quantity
and <i> explanation </i> is an explanation of the quantity that will appear in the manual.
If your Action always generates a particular set of components then the form of this command changes slightly. That is to say
if it makes no sense to use reference the isolated label for your command then this command should read:
\verbatim
componentsAreNotOptional(keys);
keys.addOutputComponent( name, "default", explanation )
\endverbatim
So for example in RESTRAINT, which always generates a component called bias and a component called force2, the components are registered
using the following code:
\verbatim
componentsAreNotOptional(keys);
keys.addOutputComponent("bias","default","the instantaneous value of the bias potential");
keys.addOutputComponent("force2","default","the instantaneous value of the squared force due to this bias potential");
\endverbatim
Lastly, if you have some method that takes in arguments and gives back one component per argument then these components should be
labelled <i>argument-name</i>_<i>description</i>. The MOVINGRESTRAINT command below gives an example of how this is done in practise.
\verbatim
DISTANCE ATOMS=1,2 LABEL=d1
DISTANCE ATOMS=3,4 LABEL=d2
MOVINGRESTRAINT ARG=d1,d2 AT0=2,2 AT1=6,6 STEP0=0 STEP1=100 KAPPA=1
\endverbatim
This command has components called d1_steer, d2_steer, d1_cntr and d2_cntr. These components describe the work done in moving the
system along the d1 and d2 axis and the instantaneous positions of the harmonic potential on the d1 and d2 axis respectively.
The various components in MOVINGRESTRAINT are registered using:
\verbatim
componentsAreNotOptional(keys);
keys.addOutputComponent("bias","default","the instantaneous value of the bias potential");
keys.addOutputComponent("force2","default","the instantaneous value of the squared force due to this bias potential");
keys.addOutputComponent("_cntr","default","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.");
keys.addOutputComponent("_work","default","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.");
\endverbatim
Appropriately labelled components can be created using the following command:
\verbatim
comp=getPntrToArgument(i)->getName()+"_cntr";
addComponent(comp); componentIsNotPeriodic(comp);
\endverbatim
They can then be set by using something like:
\verbatim
getPntrToComponent(getPntrToArgument(i)->getName()+"_work")->set(val[i]);
\endverbatim
\section reserved Reserved Keywords
To maintain some consistency for end users of the code certain keywords (e.g. ARG, PERIODIC) are reserved.
The reserved keywords for PLMD::Colvar, PLMD::function::Function and PLMD::bias::Bias are explained inside the documentation for
these actions. To use one of the registered keywords you shold insert the following command into the registerKeywords
method of your new function.
\verbatim
keys.use( keyword );
\endverbatim
where <i> keyword </i> is a string that tells the method which reserved keyword you wish to use. To be clear
when you use a reserved keyword all the parsing and registering for it is looked after automatically. In addition,
if new components are generated in the output of the action when the keyword is present the registering of those
components is also looked after elsewhere. So, for example, if you do something like:
\verbatim
keys.use("MIN")
\endverbatim
In a new PLMD::multicolvar::MultiColvar then there is no need to add the command:
\verbatim
keys.addOutputComponent("min","MIN","the minimum value. This is calculated using the formula described in the description of the "
"keyword so as to make it continuous.");
\endverbatim
As this documentation will already have been created for you elsewhere in the code.
\section errors Generating errors
You may need to check for other mistakes in input. When you find these mistakes you can report them to users using PLMD::Action::error. This routine will
output a description of how the input to your Action should appear. It takes as input a string that describes the particular nature of the error that the user has made.
\section manual Creating the rest of the manual
The remainder of the manual - the detailed description of your action and some examples of how the PLMD::Action can be used - is created
from the comments at the top of the cpp file that contains the various subroutines that your PLMD::Action performs. This is converted
to manual using Doxygen as this allows one to incorporate equations, bibliographic information and bits and pieces of HTML. At the
start of the block of manual information the following lines should appear:
\verbatim
//+PLUMEDOC TYPE ACTIONNAME
/*
\endverbatim
ACTIONAME is the first word that appears on the input line - i.e. it is the command that a user would use in input in order to make
use of your particular PLMD::Action. TYPE, meanwhile, tells Doxygen where in the manual the Docuementation should be placed. TYPE
should be one of the following:
<table align=center frame=void width=95%% cellpadding=5%%>
<tr>
<td width=5%%> <b> COLVAR </b> </td> <td> This is used if your PLMD::Action is the calculation of a CV </td>
</tr> <tr>
<td width=5%%> <b> MCOLVAR </b> </td> <td> This is used if your PLMD::Action calculates some Function of a distribution of CVs </td>
</tr> <tr>
<td width=5%%> <b> FUNCTION </b> </td> <td> This is used if your PLMD::Action calculates some Function of a set of CVs </td>
</tr> <tr>
<td width=5%%> <b> VATOM </b> </td> <td> This is used if your PLMD::Action calculates the position of a new atom e.g. for COM </td>
</tr> <tr>
<td width=5%%> <b> ANALYSIS </b> </td> <td> This is used if your PLMD::Action does some analysis of the trajectory </td>
</tr> <tr>
<td width=5%%> <b> BIAS </b> </td> <td> This is used if your PLMD::Action is a bias that adds supplemental forces to the potential in order to enhance sampling </td>
</tr> <tr>
<td width=5%%> <b> GENERIC </b> </td> <td> This should be used if you want to specify manually where in the manual your documentation should appear. If you feel this really is the correct way to incorporate your new feature please contact the core developers so as to discuss it. </td>
</tr>
</table>
Immediately after the start comment symbol you should place a single line that describes in a sentence or two what it is your PLMD::Action does. This information will
appear beside the link to your more detailed manual page in the general pages of the user manual. The code will use everything up to the first blank
line in input to create this brief description. You can then write a longer description of your PLMD::Action to appear at the start of its
particular page in the manual. As described below this description can incorporate equations and bibliographic information.
\par Creating latex formulae
You can add formulae in latex using:
\verbatim
This is an inline equation \f$s=y+x\f$ but this is an equation:
\f[
r = \sqrt{ \mathbf{s}^T \mathbf{C}^{-1} \mathbf{s} }
\f]
And this is an equation array:
\f{eqnarray*}{
f &=& \frac{1}{2} \\
g &=& \frac{2}{3}
\f}
\endverbatim
In the manual this will be translated into:
This is an inline equation \f$s=y+x\f$ but this is an equation:
\f[
r = \sqrt{ \mathbf{s}^T \mathbf{C}^{-1} \mathbf{s} }
\f]
And this is an equation array:
\f{eqnarray*}{
f &=& \frac{1}{2} \\
g &=& \frac{2}{3}
\f}
\par Creating lists
You can create lists of data using:
\verbatim
- First item in list
- Second item in list
\endverbatim
which becomes:
- First item in list
- Second item in list
\par Formatting your documentation
You can create a new section in your documentation using:
\verbatim
\section manual Creating the rest of the manual
\endverbatim
In fact I used this very command earlier in writing this page. I can therefore reference it here (\ref manual) by using:
\verbatim
\ref manual
\endverbatim
You can also reference external webpages by typing web addresses directly in the documentation.
\par Adding citations
You can create citations using:
\verbatim
\cite bibtex-tag
\endverbatim
This command uses an interface between Doxygen and bibtex to create bibliographic data. Inside
the user-doc directory you will find a bibtex file called bibliography.bib that contains all
the references that are included in the user documentation for plumed. To add your reference
you should add bibliographic data for the article you want to cite in this file.
\par Creating some examples
Your manual entry <b>must</b> contain some examples as to how your PLMD::Action. These should be included as follows:
\verbatim
\par 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.
\verbatim
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 COMPONENTS LABEL=d2
PRINT ARG=d1,d2,d2.x
\ endverbatim /*** But with no space between the \ and the endverbatim
\endverbatim
In the manual this will be converted to:
\par 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.
\verbatim
DISTANCE ATOMS=3,5 LABEL=d1
DISTANCE ATOMS=2,4 COMPONENTS LABEL=d2
PRINT ARG=d1,d2,d2.x
\endverbatim
Please be aware of the blank line between after the title of the paragraph. If this line is not present your manual will look ugly.
Also be aware that your Examples section <b> must </b> be called Examples and not Example because of a perculiarity in the
script that generates the manual.
*/