- Update to pythia8140
[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8140 / xmldoc / SettingsScheme.xml
CommitLineData
b584e2f5 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.
110
111<p/>
112a) Inside your main program you can directly set values with
113<pre>
114 pythia.readString(string)
115</pre>
116where both the variable name and the value are contained inside
117the character string, separated by blanks and/or a =, e.g.
118<pre>
119 pythia.readString("TimeShower:pTmin = 1.0");
120</pre>
121The match of the name to the database is case-insensitive. Names
122that do not match an existing variable are ignored. A warning is
123printed, however. Strings beginning with a non-alphanumeric character,
124like # or !, are assumed to be comments and are not processed at all.
125Values below the minimum or above the maximum are set at
126the respective border. For <code>bool</code> values, the following
127notation may be used interchangeably:
128<code>true = on = yes = ok = 1</code>, while everything else gives
129<code>false</code> (including but not limited to
130<code>false</code>, <code>off</code>, <code>no</code> and 0).<br/>
131
132<p/>
133b) The <code>Pythia</code> <code>readString(string)</code> method
134actually does not do changes itself, but sends on the string either
135to the <code>Settings</code> class or to <code>ParticleData</code>.
136The former holds if the string begins with a letter, the latter
137if it begins with a digit. If desired, it is possible to communicate
138directly with the corresponding <code>Settings</code> method:
139<pre>
140 pythia.settings.readString("TimeShower:pTmin = 1.0");
141</pre>
142In this case, changes intended for <code>ParticleData</code>
143would not be understood.
144
145<p/>
146c) Underlying the <code>settings.readString(string)</code> method are
147the settings-type-sensitive commands in the <code>Settings</code>, that
148are split by names containing <code>flag</code>, <code>mode</code>,
149<code>parm</code> or <code>word</code>. Thus, the example now reads
150<pre>
151 pythia.settings.parm("TimeShower:pTmin", 1.0);
152</pre>
153Such a form could be convenient e.g. if a parameter is calculated
154at the beginning of the main program, and thus is available as a
155variable rather than as a character string.
156Note that Boolean values must here be given as <code>true</code> or
157<code>false</code> i.e. there is less flexibility than with the
158previous methods.
159
160<p/>
161At the same level, there are several different methods available.
162These are included in the full description below, but normally the user
163should have no need for them.
164
165<p/>
166d) A simpler and more useful way is to collect all your changes
167in a separate file, with one line per change, e.g.
168<pre>
169 TimeShower:pTmin = 1.0
170</pre>
171Each line is read in as a string and processed with the methods already
172introduced.
173
174The file can be read by the
175<pre>
176 pythia.readFile(fileName);
177</pre>
178method (or an <code>istream</code> instead of a <code>fileName</code>).
179The file can freely mix commands to the <code>Settings</code> and
180<code>ParticleData</code> classes, and so is preferable. Lines with
181settings are handled by calls to the
182<code>pythia.settings.readString(string)</code> method.
183</li>
184
185<p/> <li>
186In the <code>pythia.init(...)</code> call, many of the various other program
187elements are initialized, making use of the current values in the database.
188Once initialized, the common <code>Settings</code> database is likely not
189consulted again by these routines. It is therefore not productive to do
190further changes in mid-run: at best nothing changes, at worst you may
191set up inconsistencies.
192
193<p/>
194A routine <code>reInit(fileName)</code> is provided, and can be used to
195zero all the maps and reinitialize them from scratch. Such a call might be
196useful if several subruns are to be made with widely different parameter
197sets - normally the maps are only built from scratch once, namely when the
198<code>Pythia()</code> object is created. A more economical alternative is
199offered by <code>resetAll()</code>, however, which sets all variables back
200to their default values.
201</li>
202
203<p/> <li>
204You may at any time obtain a listing of all variables in the
205database by calling
206<pre>
207 pythia.settings.listAll();
208</pre>
209The listing is strictly alphabetical, which at least means that names
210from the same file are kept together, but otherwise may not be so
211well-structured: important and unimportant ones will appear mixed.
212A more relevant alternative is
213<pre>
214 pythia.settings.listChanged();
215</pre>
216where you will only get those variables that differ from their
217defaults. Or you can use
218<pre>
219 pythia.settings.list("string");
220</pre>
221where only those variables with names that contain the string
222(case-insensitive match) are listed. Thus, with a string
223<code>shower</code>, the shower-related variables would be shown.
224</li>
225
226<p/> <li>
227The above listings are in a tabular form that cannot be read
228back in. Assuming you want to save all changed settings (maybe because
229you read in changes from several files), you can do that by calling
230<pre>
231 pythia.settings.writeFile(fileName);
232</pre>
233This file could then directly be read in by
234<code>readFile(fileName)</code> in a subsequent (identical) run.
235Some variants of this command are listed below.
236</li>
237</ol>
238
239<h3>Methods</h3>
240
241The complete list of methods and arguments is as follows. Most of the
242ones of interest to the user have already been mentioned above.
243Others can be used, but the same functionality is better achieved
244by higher-level routines. Some are part of the internal machinery,
245and should not be touched by user.
246
247<p/>
248Note that there is no <code>Settings::readFile(...)</code> method.
249The intention is that you should use <code>Pythia::readFile(...)</code>.
250It parses and decides which individual lines should be sent on to
251<code>Settings::readString(...)</code>.
252
253<method name="Settings::Settings()">
254the constructor, which takes no arguments. Internal.
255</method>
256
257<method name="bool Settings::initPtr(Info* infoPtrIn)">
258initialize pointer to error-message database. Internal.
259</method>
260
261<method name="bool Settings::init(string
262startFile = &quot;../xmldoc/Index.xml&quot;, bool append = false,
263ostream& os = cout)">
264read in the settings database.
265<argument name="startFile" default="&quot;../xmldoc/Index.xml&quot;">
266read in the settings from all the files listed in this file, and
267assumed to be located in the same subdirectory.
268</argument>
269<argument name="append" default="false">
270By default nothing is done if the method has already been called once.
271If true the further settings read in are added to the current database.
272</argument>
273<argument name="os" default="cout">
274stream for error printout.
275</argument>
276<note>Note:</note> The method returns false if it fails.
277</method>
278
279<method name="bool Settings::reInit(string
280startFile = &quot;../xmldoc/Index.xml&quot;, ostream& os = cout)">
281overwrite the existing database.
282<argument name="startFile" default="&quot;../xmldoc/Index.xml&quot;">
283read in the settings from all the files listed in this file, and
284assumed to be located in the same subdirectory.
285</argument>
286<argument name="os" default="cout">
287stream for error printout.
288</argument>
289<note>Note:</note> The method returns false if it fails.
290</method>
291
292<method name="bool Settings::readString(string line,
293bool warn = true, ostream& os = cout)">
294read in a string, and change the relevant quantity in the database.
295It is normally used indirectly, via
296<code>Pythia::readString(...)</code> and
297<code>Pythia::readFile(...)</code>.
298<argument name="line">
299the string to be interpreted as an instruction.
300</argument>
301<argument name="warn" default="true">
302write a warning message or not whenever the instruction does not make
303sense, e.g. if the variable does not exist in the databases.
304</argument>
305<argument name="os" default="cout">
306stream for error printout.
307</argument>
308<note>Note:</note> the method returns false if it fails to
309make sense out of the input string.
310</method>
311
312<method name="bool Settings::writeFile(string toFile,
313bool writeAll = false)">
314</method>
315<methodmore name="bool Settings::writeFile(ostream& os = cout,
316bool writeAll = false)">
317write current settings to a file or to an <code>ostream</code>.
318<argument name="toFile, os">
319file or stream on which settings are written.
320</argument>
321<argument name="writeAll" default="false">
322normally only settings that have been changed are written,
323but if true then all settings are output.
324</argument>
325<note>Note:</note> the method returns false if it fails.
326</methodmore>
327
328<method name="void Settings::listAll(ostream& os = cout)">
329</method>
330<methodmore name="void Settings::listChanged(ostream& os = cout)">
331</methodmore>
332<methodmore name="void Settings::list(string match,
333ostream& os = cout)">
334list all or changed settings, or a group of them.
335<argument name="match">
336list all those settings where the name contains
337the <code>match</code> (sub)string (case-insensitive).
338</argument>
339<argument name="os" default="cout">
340output stream for the listing.
341</argument>
342</methodmore>
343
344<method name="void Settings::resetAll()">
345reset all current values to their defaults.
346</method>
347
348<method name="bool Settings::isFlag(string key)">
349</method>
350<methodmore name="bool Settings::isMode(string key)">
351</methodmore>
352<methodmore name="bool Settings::isParm(string key)">
353</methodmore>
354<methodmore name="bool Settings::isWord(string key)">
355return true if an entry of the given name and kind
356exists, else false.
357</methodmore>
358
359<method name="void Settings::addFlag(string key, bool default)">
360</method>
361<methodmore name="void Settings::addMode(string key,
362int default, bool hasMin, bool hasMax, int min, int max)">
363</methodmore>
364<methodmore name="void Settings::addParm(string key,
365double default, bool hasMin, bool hasMax, double min, double max)">
366</methodmore>
367<methodmore name="void Settings::addWord(string key,
368string default)">
369add an entry of the respective kind to the database. The name and default
370value always has to be supplied, for <code>Mode</code> and
371<code>Word</code> additionally if lower and/or upper limits are to be
372imposed and, if so, what those limit are.
373</methodmore>
374
375<method name="bool Settings::flag(string key)">
376</method>
377<methodmore name="int Settings::mode(string key)">
378</methodmore>
379<methodmore name="double Settings::parm(string key)">
380</methodmore>
381<methodmore name="string Settings::word(string key)">
382return the current value of the respective setting. If the name
383does not exist in the database, a value <code>false</code>,
384<code>0</code>, <code>0.</code> and <code>&quot; &quot;</code>
385is returned, respectively.
386</methodmore>
387
388<method name="void Settings::flag(string key, bool now)">
389</method>
390<methodmore name="void Settings::mode(string key, int now)">
391</methodmore>
392<methodmore name="void Settings::parm(string key, double now)">
393</methodmore>
394<methodmore name="void Settings::word(string key, string now)">
395change the current value of the respective setting to the provided
396new value. If lower or upper limits have been set, input values
397outside the allowed range are reinterpreted as being a the nearest
398limit.
399</methodmore>
400
401<method name="void Settings::forceMode(string key, int now)">
402</method>
403<methodmore name="void Settings::forceParm(string key, double now)">
404as above, but do not check lower and upper limits, so that the current
405value can be put outside the intended borders.
406</methodmore>
407
408<method name="void Settings::resetFlag(string key)">
409</method>
410<methodmore name="void Settings::resetMode(string key)">
411</methodmore>
412<methodmore name="void Settings::resetParm(string key)">
413</methodmore>
414<methodmore name="void Settings::resetWord(string key)">
415reset the current value to the default one.
416</methodmore>
417
418</chapter>
419
420<!-- Copyright (C) 2010 Torbjorn Sjostrand -->