source: HiSusy/trunk/Pythia8/pythia8170/xmldoc/SettingsScheme.xml @ 1

Last change on this file since 1 was 1, checked in by zerwas, 11 years ago

first import of structure, PYTHIA8 and DELPHES

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