1 | <chapter name="The Settings Scheme"> |
---|
2 | |
---|
3 | <h2>The Settings Scheme</h2> |
---|
4 | |
---|
5 | The <code>Settings</code> class keeps track of all the flags, modes, |
---|
6 | parameters and words used during the event generation. As such, it |
---|
7 | serves all the <code>Pythia</code> program elements from one central |
---|
8 | repository. Accessing it allows the user to modify the generator |
---|
9 | behaviour. |
---|
10 | |
---|
11 | <p/> |
---|
12 | Each <code>Pythia</code> object has a public member <code>settings</code> |
---|
13 | of the <code>Settings</code> class. Therefore you access the |
---|
14 | settings methods as <code>pythia.settings.command(argument)</code>, |
---|
15 | assuming that <code>pythia</code> is an instance of the <code>Pythia</code> |
---|
16 | class. Further, for the most frequent user tasks, <code>Pythia</code> |
---|
17 | methods have been defined, so that <code>pythia.command(argument)</code> |
---|
18 | would work, see further below. |
---|
19 | |
---|
20 | <p/> |
---|
21 | The central section on this page is the Operation one. The preceding |
---|
22 | concepts section is there mainly to introduce the basic structure and |
---|
23 | the set of properties that can be accessed. The subsequent sections |
---|
24 | provide a complete listing of the existing public methods, which most |
---|
25 | users probably will have little interaction with. |
---|
26 | |
---|
27 | <h3>Concepts</h3> |
---|
28 | |
---|
29 | We distinguish four kinds of user-modifiable variables, by the way |
---|
30 | they have to be stored: |
---|
31 | <ol> |
---|
32 | <li>Flags are on/off switches, and are stored as <code>bool</code>.</li> |
---|
33 | <li>Modes corresponds to a finite enumeration of separate options, |
---|
34 | and are stored as <code>int</code>.</li> |
---|
35 | <li>Parameters take a continuum of values, and are stored as |
---|
36 | <code>double</code>. The shorthand notation parm is used in the C++ |
---|
37 | code and XML tags, so that all four kinds are represented by |
---|
38 | four-letter type names.</li> |
---|
39 | <li>Words are simple character strings and are stored as |
---|
40 | <code>string</code>. No blanks or double quotation marks (") may |
---|
41 | appear inside a word, the former to simplify parsing of an input file |
---|
42 | and the latter not to cause conflicts with XML attribute delimiters. |
---|
43 | Currently the main application is to store file names.</li> |
---|
44 | </ol> |
---|
45 | |
---|
46 | <p/> |
---|
47 | In general, each variable stored in <code>Settings</code> is associated |
---|
48 | with four kinds of information: |
---|
49 | <ul> |
---|
50 | <li>The variable name, of the form <code>class:name</code> |
---|
51 | (or <code>file:name</code>, usually these agree), e.g. |
---|
52 | <code>TimeShower:pTmin</code>. The class/file part usually identifies |
---|
53 | the <code>.xml</code> file where the variable is defined, and the part of |
---|
54 | the program where it is used, but such a connection cannot be strictly |
---|
55 | upheld, since e.g. the same variable may be used in a few different |
---|
56 | cases (even if most of them are not).</li> |
---|
57 | <li>The default value, set in the original declaration, and intended |
---|
58 | to represent a reasonable choice.</li> |
---|
59 | <li>The current value, which differs from the default when the user so |
---|
60 | requests.</li> |
---|
61 | <li>An allowed range of values, represented by meaningful |
---|
62 | minimum and maximum values. This has no sense for a <code>flag</code> |
---|
63 | or a <code>word</code> (and is not used there), is usually rather |
---|
64 | well-defined for a <code>mode</code>, but less so for a <code>parm</code>. |
---|
65 | Often the allowed range exaggerates the degree of our current knowledge, |
---|
66 | so as not to restrict too much what the user can do. One may choose |
---|
67 | not to set the lower or upper limit, in which case the range is |
---|
68 | open-ended.</li> |
---|
69 | </ul> |
---|
70 | |
---|
71 | <p/> |
---|
72 | Technically, the <code>Settings</code> class is implemented with the |
---|
73 | help of four separate maps, one for each kind of variable, with the |
---|
74 | variable <code>name</code> used as key. |
---|
75 | |
---|
76 | <h3>Operation</h3> |
---|
77 | |
---|
78 | The normal flow of setting values is: |
---|
79 | |
---|
80 | <ol> |
---|
81 | |
---|
82 | <p/> <li> |
---|
83 | When a <code>Pythia</code> object <code>pythia </code>is created, |
---|
84 | the member <code>pythia.settings</code> is asked to scan the files |
---|
85 | listed in the <code>Index.xml</code> file in the <code>xmldoc</code> |
---|
86 | subdirectory. |
---|
87 | |
---|
88 | <p/> |
---|
89 | In all of the files scanned, lines beginning with |
---|
90 | <code><flag</code>, <code><mode</code>, <code><parm</code> |
---|
91 | or <code><word</code> are identified, and the information on |
---|
92 | such a line is used to define a new flag, mode, parameter or word. |
---|
93 | To exemplify, consider a line |
---|
94 | <pre> |
---|
95 | <parm name="TimeShower:pTmin" default="0.5" min="0.1" max="2.0"> |
---|
96 | </pre> |
---|
97 | which appears in the <code>TimeShower.xml</code> file, and there |
---|
98 | defines a parameter <code>TimeShower:pTmin</code> with default value |
---|
99 | 0.5 GeV and allowed variation in the range 0.1 - 2.0 GeV. The min |
---|
100 | and max values are optional. |
---|
101 | <note>Important:</note> the values in the <code>.xml</code> files should |
---|
102 | not be changed, except by the PYTHIA authors. Any changes should be |
---|
103 | done with the help of the methods described below. |
---|
104 | </li> |
---|
105 | |
---|
106 | <p/> <li> |
---|
107 | Between the creation of the <code>Pythia</code> object and the |
---|
108 | <code>init</code> call for it, you may use several alternative |
---|
109 | methods to modify some of the default values. The same variable |
---|
110 | can be changed several times. If so, it is the last read value |
---|
111 | that counts. The two special |
---|
112 | <code><aloc href="Tunes">Tune:ee</aloc></code> and |
---|
113 | <code><aloc href="Tunes">Tune:pp</aloc></code> |
---|
114 | modes are expanded to change several settings in one go, but these obey |
---|
115 | the same ordering rules. |
---|
116 | |
---|
117 | <p/> |
---|
118 | a) Inside your main program you can directly set values with |
---|
119 | <pre> |
---|
120 | pythia.readString(string) |
---|
121 | </pre> |
---|
122 | where both the variable name and the value are contained inside |
---|
123 | the character string, separated by blanks and/or a =, e.g. |
---|
124 | <pre> |
---|
125 | pythia.readString("TimeShower:pTmin = 1.0"); |
---|
126 | </pre> |
---|
127 | The match of the name to the database is case-insensitive. Names |
---|
128 | that do not match an existing variable are ignored. A warning is |
---|
129 | printed, however. Strings beginning with a non-alphanumeric character, |
---|
130 | like # or !, are assumed to be comments and are not processed at all. |
---|
131 | Values below the minimum or above the maximum are set at |
---|
132 | the respective border. For <code>bool</code> values, the following |
---|
133 | notation may be used interchangeably: |
---|
134 | <code>true = on = yes = ok = 1</code>, while everything else gives |
---|
135 | <code>false</code> (including but not limited to |
---|
136 | <code>false</code>, <code>off</code>, <code>no</code> and 0).<br/> |
---|
137 | |
---|
138 | <p/> |
---|
139 | b) The <code>Pythia</code> <code>readString(string)</code> method |
---|
140 | actually does not do changes itself, but sends on the string either |
---|
141 | to the <code>Settings</code> class or to <code>ParticleData</code>. |
---|
142 | The former holds if the string begins with a letter, the latter |
---|
143 | if it begins with a digit. If desired, it is possible to communicate |
---|
144 | directly with the corresponding <code>Settings</code> method: |
---|
145 | <pre> |
---|
146 | pythia.settings.readString("TimeShower:pTmin = 1.0"); |
---|
147 | </pre> |
---|
148 | In this case, changes intended for <code>ParticleData</code> |
---|
149 | would not be understood. |
---|
150 | |
---|
151 | <p/> |
---|
152 | c) Underlying the <code>settings.readString(string)</code> method are |
---|
153 | the settings-type-sensitive commands in the <code>Settings</code>, that |
---|
154 | are split by names containing <code>flag</code>, <code>mode</code>, |
---|
155 | <code>parm</code> or <code>word</code>. Thus, the example now reads |
---|
156 | <pre> |
---|
157 | pythia.settings.parm("TimeShower:pTmin", 1.0); |
---|
158 | </pre> |
---|
159 | Such a form could be convenient e.g. if a parameter is calculated |
---|
160 | at the beginning of the main program, and thus is available as a |
---|
161 | variable rather than as a character string. |
---|
162 | Note that Boolean values must here be given as <code>true</code> or |
---|
163 | <code>false</code> i.e. there is less flexibility than with the |
---|
164 | previous methods. |
---|
165 | |
---|
166 | <p/> |
---|
167 | At the same level, there are several different methods available. |
---|
168 | These are included in the full description below, but normally the user |
---|
169 | should have no need for them. |
---|
170 | |
---|
171 | <p/> |
---|
172 | d) A simpler and more useful way is to collect all your changes |
---|
173 | in a separate file, with one line per change, e.g. |
---|
174 | <pre> |
---|
175 | TimeShower:pTmin = 1.0 |
---|
176 | </pre> |
---|
177 | Each line is read in as a string and processed with the methods already |
---|
178 | introduced. |
---|
179 | |
---|
180 | The file can be read by the |
---|
181 | <pre> |
---|
182 | pythia.readFile(fileName); |
---|
183 | </pre> |
---|
184 | method (or an <code>istream</code> instead of a <code>fileName</code>). |
---|
185 | The file can freely mix commands to the <code>Settings</code> and |
---|
186 | <code>ParticleData</code> classes, and so is preferable. Lines with |
---|
187 | settings are handled by calls to the |
---|
188 | <code>pythia.settings.readString(string)</code> method. |
---|
189 | </li> |
---|
190 | |
---|
191 | <p/> <li> |
---|
192 | In the <code>pythia.init(...)</code> call, many of the various other program |
---|
193 | elements are initialized, making use of the current values in the database. |
---|
194 | Once initialized, the common <code>Settings</code> database is likely not |
---|
195 | consulted again by these routines. It is therefore not productive to do |
---|
196 | further changes in mid-run: at best nothing changes, at worst you may |
---|
197 | set up inconsistencies. |
---|
198 | |
---|
199 | <p/> |
---|
200 | A routine <code>reInit(fileName)</code> is provided, and can be used to |
---|
201 | zero all the maps and reinitialize them from scratch. Such a call might be |
---|
202 | useful if several subruns are to be made with widely different parameter |
---|
203 | sets - normally the maps are only built from scratch once, namely when the |
---|
204 | <code>Pythia()</code> object is created. A more economical alternative is |
---|
205 | offered by <code>resetAll()</code>, however, which sets all variables back |
---|
206 | to their default values. |
---|
207 | </li> |
---|
208 | |
---|
209 | <p/> <li> |
---|
210 | You may at any time obtain a listing of all variables in the |
---|
211 | database by calling |
---|
212 | <pre> |
---|
213 | pythia.settings.listAll(); |
---|
214 | </pre> |
---|
215 | The listing is strictly alphabetical, which at least means that names |
---|
216 | from the same file are kept together, but otherwise may not be so |
---|
217 | well-structured: important and unimportant ones will appear mixed. |
---|
218 | A more relevant alternative is |
---|
219 | <pre> |
---|
220 | pythia.settings.listChanged(); |
---|
221 | </pre> |
---|
222 | where you will only get those variables that differ from their |
---|
223 | defaults. Or you can use |
---|
224 | <pre> |
---|
225 | pythia.settings.list("string"); |
---|
226 | </pre> |
---|
227 | where only those variables with names that contain the string |
---|
228 | (case-insensitive match) are listed. Thus, with a string |
---|
229 | <code>shower</code>, the shower-related variables would be shown. |
---|
230 | </li> |
---|
231 | |
---|
232 | <p/> <li> |
---|
233 | The above listings are in a tabular form that cannot be read |
---|
234 | back in. Assuming you want to save all changed settings (maybe because |
---|
235 | you read in changes from several files), you can do that by calling |
---|
236 | <pre> |
---|
237 | pythia.settings.writeFile(fileName); |
---|
238 | </pre> |
---|
239 | This file could then directly be read in by |
---|
240 | <code>readFile(fileName)</code> in a subsequent (identical) run. |
---|
241 | Some variants of this command are listed below. |
---|
242 | </li> |
---|
243 | </ol> |
---|
244 | |
---|
245 | <h3>Methods</h3> |
---|
246 | |
---|
247 | The complete list of methods and arguments is as follows. Most of the |
---|
248 | ones of interest to the user have already been mentioned above. |
---|
249 | Others can be used, but the same functionality is better achieved |
---|
250 | by higher-level routines. Some are part of the internal machinery, |
---|
251 | and should not be touched by user. |
---|
252 | |
---|
253 | <p/> |
---|
254 | Note that there is no <code>Settings::readFile(...)</code> method. |
---|
255 | The intention is that you should use <code>Pythia::readFile(...)</code>. |
---|
256 | It parses and decides which individual lines should be sent on to |
---|
257 | <code>Settings::readString(...)</code>. |
---|
258 | |
---|
259 | <method name="Settings::Settings()"> |
---|
260 | the constructor, which takes no arguments. Internal. |
---|
261 | </method> |
---|
262 | |
---|
263 | <method name="bool Settings::initPtr(Info* infoPtrIn)"> |
---|
264 | initialize pointer to error-message database. Internal. |
---|
265 | </method> |
---|
266 | |
---|
267 | <method name="bool Settings::init(string |
---|
268 | startFile = "../xmldoc/Index.xml", bool append = false, |
---|
269 | ostream& os = cout)"> |
---|
270 | read in the settings database. |
---|
271 | <argument name="startFile" default=""../xmldoc/Index.xml""> |
---|
272 | read in the settings from all the files listed in this file, and |
---|
273 | assumed to be located in the same subdirectory. |
---|
274 | </argument> |
---|
275 | <argument name="append" default="false"> |
---|
276 | By default nothing is done if the method has already been called once. |
---|
277 | If true the further settings read in are added to the current database. |
---|
278 | </argument> |
---|
279 | <argument name="os" default="cout"> |
---|
280 | stream for error printout. |
---|
281 | </argument> |
---|
282 | <note>Note:</note> The method returns false if it fails. |
---|
283 | </method> |
---|
284 | |
---|
285 | <method name="bool Settings::reInit(string |
---|
286 | startFile = "../xmldoc/Index.xml", ostream& os = cout)"> |
---|
287 | overwrite the existing database. |
---|
288 | <argument name="startFile" default=""../xmldoc/Index.xml""> |
---|
289 | read in the settings from all the files listed in this file, and |
---|
290 | assumed to be located in the same subdirectory. |
---|
291 | </argument> |
---|
292 | <argument name="os" default="cout"> |
---|
293 | stream for error printout. |
---|
294 | </argument> |
---|
295 | <note>Note:</note> The method returns false if it fails. |
---|
296 | </method> |
---|
297 | |
---|
298 | <method name="bool Settings::readString(string line, |
---|
299 | bool warn = true, ostream& os = cout)"> |
---|
300 | read in a string, and change the relevant quantity in the database. |
---|
301 | It is normally used indirectly, via |
---|
302 | <code>Pythia::readString(...)</code> and |
---|
303 | <code>Pythia::readFile(...)</code>. |
---|
304 | <argument name="line"> |
---|
305 | the string to be interpreted as an instruction. |
---|
306 | </argument> |
---|
307 | <argument name="warn" default="true"> |
---|
308 | write a warning message or not whenever the instruction does not make |
---|
309 | sense, e.g. if the variable does not exist in the databases. |
---|
310 | </argument> |
---|
311 | <argument name="os" default="cout"> |
---|
312 | stream for error printout. |
---|
313 | </argument> |
---|
314 | <note>Note:</note> the method returns false if it fails to |
---|
315 | make sense out of the input string. |
---|
316 | </method> |
---|
317 | |
---|
318 | <method name="bool Settings::writeFile(string toFile, |
---|
319 | bool writeAll = false)"> |
---|
320 | </method> |
---|
321 | <methodmore name="bool Settings::writeFile(ostream& os = cout, |
---|
322 | bool writeAll = false)"> |
---|
323 | write current settings to a file or to an <code>ostream</code>. |
---|
324 | <argument name="toFile, os"> |
---|
325 | file or stream on which settings are written. |
---|
326 | </argument> |
---|
327 | <argument name="writeAll" default="false"> |
---|
328 | normally only settings that have been changed are written, |
---|
329 | but if true then all settings are output. |
---|
330 | </argument> |
---|
331 | <note>Note:</note> the method returns false if it fails. |
---|
332 | </methodmore> |
---|
333 | |
---|
334 | <method name="void Settings::listAll(ostream& os = cout)"> |
---|
335 | </method> |
---|
336 | <methodmore name="void Settings::listChanged(ostream& os = cout)"> |
---|
337 | </methodmore> |
---|
338 | <methodmore name="void Settings::list(string match, |
---|
339 | ostream& os = cout)"> |
---|
340 | list all or changed settings, or a group of them. |
---|
341 | <argument name="match"> |
---|
342 | list all those settings where the name contains |
---|
343 | the <code>match</code> (sub)string (case-insensitive). |
---|
344 | </argument> |
---|
345 | <argument name="os" default="cout"> |
---|
346 | output stream for the listing. |
---|
347 | </argument> |
---|
348 | </methodmore> |
---|
349 | |
---|
350 | <method name="void Settings::resetAll()"> |
---|
351 | reset all current values to their defaults. |
---|
352 | </method> |
---|
353 | |
---|
354 | <method name="bool Settings::isFlag(string key)"> |
---|
355 | </method> |
---|
356 | <methodmore name="bool Settings::isMode(string key)"> |
---|
357 | </methodmore> |
---|
358 | <methodmore name="bool Settings::isParm(string key)"> |
---|
359 | </methodmore> |
---|
360 | <methodmore name="bool Settings::isWord(string key)"> |
---|
361 | return true if an entry of the given name and kind |
---|
362 | exists, else false. |
---|
363 | </methodmore> |
---|
364 | |
---|
365 | <method name="void Settings::addFlag(string key, bool default)"> |
---|
366 | </method> |
---|
367 | <methodmore name="void Settings::addMode(string key, |
---|
368 | int default, bool hasMin, bool hasMax, int min, int max)"> |
---|
369 | </methodmore> |
---|
370 | <methodmore name="void Settings::addParm(string key, |
---|
371 | double default, bool hasMin, bool hasMax, double min, double max)"> |
---|
372 | </methodmore> |
---|
373 | <methodmore name="void Settings::addWord(string key, |
---|
374 | string default)"> |
---|
375 | add an entry of the respective kind to the database. The name and default |
---|
376 | value always has to be supplied, for <code>Mode</code> and |
---|
377 | <code>Word</code> additionally if lower and/or upper limits are to be |
---|
378 | imposed and, if so, what those limit are. |
---|
379 | </methodmore> |
---|
380 | |
---|
381 | <method name="bool Settings::flag(string key)"> |
---|
382 | </method> |
---|
383 | <methodmore name="int Settings::mode(string key)"> |
---|
384 | </methodmore> |
---|
385 | <methodmore name="double Settings::parm(string key)"> |
---|
386 | </methodmore> |
---|
387 | <methodmore name="string Settings::word(string key)"> |
---|
388 | return the current value of the respective setting. If the name |
---|
389 | does not exist in the database, a value <code>false</code>, |
---|
390 | <code>0</code>, <code>0.</code> and <code>" "</code> |
---|
391 | is returned, respectively. |
---|
392 | </methodmore> |
---|
393 | |
---|
394 | <method name="map<string, Flag> Settings::getFlagMap(string match)"> |
---|
395 | </method> |
---|
396 | <methodmore name="map<string, Mode> Settings::getModeMap(string match)"> |
---|
397 | </methodmore> |
---|
398 | <methodmore name="map<string, Parm> Settings::getParmMap(string match)"> |
---|
399 | </methodmore> |
---|
400 | <methodmore name="map<string, Word> Settings::getWordMap(string match)"> |
---|
401 | return a map of all settings of the respective type that contain the |
---|
402 | string "match" in its name. |
---|
403 | </methodmore> |
---|
404 | |
---|
405 | <method name="void Settings::flag(string key, bool now)"> |
---|
406 | </method> |
---|
407 | <methodmore name="void Settings::mode(string key, int now)"> |
---|
408 | </methodmore> |
---|
409 | <methodmore name="void Settings::parm(string key, double now)"> |
---|
410 | </methodmore> |
---|
411 | <methodmore name="void Settings::word(string key, string now)"> |
---|
412 | change the current value of the respective setting to the provided |
---|
413 | new value. If lower or upper limits have been set, input values |
---|
414 | outside the allowed range are reinterpreted as being a the nearest |
---|
415 | limit. |
---|
416 | </methodmore> |
---|
417 | |
---|
418 | <method name="void Settings::forceMode(string key, int now)"> |
---|
419 | </method> |
---|
420 | <methodmore name="void Settings::forceParm(string key, double now)"> |
---|
421 | as above, but do not check lower and upper limits, so that the current |
---|
422 | value can be put outside the intended borders. |
---|
423 | </methodmore> |
---|
424 | |
---|
425 | <method name="void Settings::resetFlag(string key)"> |
---|
426 | </method> |
---|
427 | <methodmore name="void Settings::resetMode(string key)"> |
---|
428 | </methodmore> |
---|
429 | <methodmore name="void Settings::resetParm(string key)"> |
---|
430 | </methodmore> |
---|
431 | <methodmore name="void Settings::resetWord(string key)"> |
---|
432 | reset the current value to the default one. |
---|
433 | </methodmore> |
---|
434 | |
---|
435 | </chapter> |
---|
436 | |
---|
437 | <!-- Copyright (C) 2012 Torbjorn Sjostrand --> |
---|