]>
Commit | Line | Data |
---|---|---|
5ad4eb21 | 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 in the program. As such, it serves the other program | |
7 | elements from one central repository. Accessing it allows the user to | |
8 | modify the behaviour of the program. The <code>Settings</code> class is | |
9 | purely static, i.e. you can interact with it directly by | |
10 | <code>Settings::command(argument)</code>. | |
11 | However, a <code>settings</code> object of the <code>Settings</code> class | |
12 | is a public member of the <code>Pythia</code> class, so an alternative | |
13 | notation would be <code>pythia.settings.command(argument)</code>, | |
14 | assuming that <code>pythia</code> is an instance of the <code>Pythia</code> | |
15 | class. Further, for the most frequent user tasks, <code>Pythia</code> | |
16 | methods have been defined, so that <code>pythia.command(argument)</code> | |
17 | would work, see further below. | |
18 | ||
19 | <h3>Concepts</h3> | |
20 | ||
21 | We distinguish four kinds of user-modifiable variables, by the way | |
22 | they have to be stored: | |
23 | <ol> | |
24 | <li>Flags are on/off switches, and are stored as <code>bool</code>.</li> | |
25 | <li>Modes corresponds to a finite enumeration of separate options, | |
26 | and are stored as <code>int</code>.</li> | |
27 | <li>Parameters take a continuum of values, and are stored as | |
28 | <code>double</code>. The shorthand notation parm is used in the C++ | |
29 | code and XML tags, so that all four kinds are represented by | |
30 | four-letter type names.</li> | |
31 | <li>Words are simple character strings and are stored as | |
32 | <code>string</code>. No blanks or double quotation marks (") may | |
33 | appear inside a word, the former to simplify parsing of an input file | |
34 | and the latter not to cause conflicts with XML attribute delimiters. | |
35 | Currently the main application is to store file names.</li> | |
36 | </ol> | |
37 | ||
38 | <p/> | |
39 | In general, each variable stored in <code>Settings</code> is associated | |
40 | with four kinds of information: | |
41 | <ul> | |
42 | <li>The variable name, of the form <code>class:name</code> | |
43 | (or <code>file:name</code>, usually these agree), e.g. | |
44 | <code>TimeShower:pTmin</code>. The class/file part usually identifies | |
45 | the <code>.xml</code> file where the variable is defined, and the part of | |
46 | the program where it is used, but such a connection cannot be strictly | |
47 | upheld, since e.g. the same variable may be used in a few different | |
48 | cases (even if most of them are not).</li> | |
49 | <li>The default value, set in the original declaration, and intended | |
50 | to represent a reasonable choice.</li> | |
51 | <li>The current value, which differs from the default when the user so | |
52 | requests.</li> | |
53 | <li>An allowed range of values, represented by meaningful | |
54 | minimum and maximum values. This has no sense for a <code>flag</code> | |
55 | or a <code>word</code> (and is not used there), is usually rather | |
56 | well-defined for a <code>mode</code>, but less so for a <code>parm</code>. | |
57 | Often the allowed range exaggerates the degree of our current knowledge, | |
58 | so as not to restrict too much what the user can do. One may choose | |
59 | not to set the lower or upper limit, in which case the range is | |
60 | open-ended.</li> | |
61 | </ul> | |
62 | ||
63 | <p/> | |
64 | Technically, the <code>Settings</code> class is implemented with the | |
65 | help of four separate maps, one for each kind of variable, with the | |
66 | variable <code>name</code> used as key. | |
67 | ||
68 | <h3>Operation</h3> | |
69 | ||
70 | The normal flow of setting values is: | |
71 | ||
72 | <ol> | |
73 | ||
74 | <p/> <li> | |
75 | When a <code>Pythia</code> object <code>pythia </code>is created, | |
76 | the member <code>pythia.settings</code> is asked to scan the files | |
77 | listed in the <code>Index.xml</code> file in the <code>xmldoc</code> | |
78 | subdirectory. | |
79 | ||
80 | <p/> | |
81 | In all of the files scanned, lines beginning with | |
82 | <code><flag</code>, <code><mode</code>, <code><parm</code> | |
83 | or <code><word</code> are identified, and the information on | |
84 | such a line is used to define a new flag, mode, parameter or word. | |
85 | To exemplify, consider a line | |
86 | <pre> | |
87 | <parm name="TimeShower:pTmin" default="0.5" min="0.1" max="2.0"> | |
88 | </pre> | |
89 | which appears in the <code>TimeShower.xml</code> file, and there | |
90 | defines a parameter <code>TimeShower:pTmin</code> with default value | |
91 | 0.5 GeV and allowed variation in the range 0.1 - 2.0 GeV. The min | |
92 | and max values are optional. | |
93 | <note>Important:</note> the values in the <code>.xml</code> files should | |
94 | not be changed, except by the PYTHIA authors. Any changes should be | |
95 | done with the help of the methods described below. | |
96 | </li> | |
97 | ||
98 | <p/> <li> | |
99 | Between the creation of the <code>Pythia</code> object and the | |
100 | <code>init</code> call for it, you may use several alternative | |
101 | methods to modify some of the default values. | |
102 | ||
103 | <p/> | |
104 | a) Inside your main program you can directly set values with | |
105 | <pre> | |
106 | pythia.readString(string) | |
107 | </pre> | |
108 | where both the variable name and the value are contained inside | |
109 | the character string, separated by blanks and/or a =, e.g. | |
110 | <pre> | |
111 | pythia.readString("TimeShower:pTmin = 1.0"); | |
112 | </pre> | |
113 | The match of the name to the database is case-insensitive. Names | |
114 | that do not match an existing variable are ignored. A warning is | |
115 | printed, however, unless an optional second argument <code>false</code> | |
116 | is used. Strings beginning with a non-alphanumeric character, like | |
117 | # or !, are assumed to be comments and are not processed at all. | |
118 | Values below the minimum or above the maximum are set at | |
119 | the respective border. For <code>bool</code> values, the following | |
120 | notation may be used interchangeably: | |
121 | <code>true = on = yes = ok = 1</code>, while everything else gives | |
122 | <code>false</code> (including but not limited to | |
123 | <code>false</code>, <code>off</code>, <code>no</code> and 0).<br/> | |
124 | ||
125 | <p/> | |
126 | b) The <code>Pythia</code> <code>readString(string)</code> method | |
127 | actually does not do changes itself, but sends on the string either | |
128 | to the <code>Settings</code> class or to <code>ParticleData</code>. | |
129 | If desired, it is possible to communicate | |
130 | directly with the corresponding <code>Settings</code> method: | |
131 | <pre> | |
132 | pythia.settings.readString("TimeShower:pTmin = 1.0"); | |
133 | </pre> | |
134 | In this case, changes intended for <code>ParticleData</code> | |
135 | would not be understood. | |
136 | ||
137 | <p/> | |
138 | c) Underlying the <code>settings.readString(string)</code> method are | |
139 | the settings-type-sensitive commands in the <code>Settings</code>, that | |
140 | are split by names containing <code>flag</code>, <code>mode</code>, | |
141 | <code>parm</code> or <code>word</code>. Thus, the example now reads | |
142 | <pre> | |
143 | pythia.settings.parm("TimeShower:pTmin", 1.0); | |
144 | </pre> | |
145 | Boolean values should here be given as <code>true</code> or | |
146 | <code>false</code> i.e. there is less flexibility in the lower-level | |
147 | methods. | |
148 | ||
149 | <p/> | |
150 | At the same level, there are several different methods available. | |
151 | We here show the ones for <code>mode</code>, but corresponding methods | |
152 | exist for <code>flag</code>, <code>parm</code> and <code>word</code>, | |
153 | with obvious restrictions where <code>min</code> and <code>max</code> | |
154 | are not defined. Again name comparisons are case-insensitive. | |
155 | <method name="mode( name)"> | |
156 | gives the current value, | |
157 | </method> | |
158 | <method name="mode( name, value)"> | |
159 | sets the current value, | |
160 | </method> | |
161 | <method name="isMode( name)"> | |
162 | tells whether a mode has been defined or not, | |
163 | </method> | |
164 | <method name="addMode( name, default, min, max)"> | |
165 | defines a new mode, | |
166 | </method> | |
167 | <method name="forceMode( name, value)"> | |
168 | sets the value, also when outside the recommended bounds (and it is | |
169 | completely up to you to face the consequences), | |
170 | </method> | |
171 | <method name="resetMode( name)"> | |
172 | resets the current value to the default one. | |
173 | </method> | |
174 | ||
175 | <p/> | |
176 | Normally the user should have no need for these methods. The | |
177 | main exception is when some of the variables defined on the | |
178 | <aloc href="MainProgramSettings">Main-Program Settings</aloc> | |
179 | page are used to set run-specific information | |
180 | (like the CM energy or the number of events to generate) in an external | |
181 | file (see 2d below) and these variables are to be read into the main | |
182 | program. Then the <code>flag(name)</code>, <code>mode(name)</code> | |
183 | <code>parm(name)</code> and <code>word(name)</code> methods are to | |
184 | be used, see e.g. the main programs in the <code>examples</code> | |
185 | subdirectory to find out how it works. | |
186 | ||
187 | <p/> | |
188 | d) A simpler and more useful way is to collect all your changes | |
189 | in a separate file, with one line per change, e.g. | |
190 | <pre> | |
191 | TimeShower:pTmin = 1.0 | |
192 | </pre> | |
193 | Each line is read in as a string and processed with the methods already | |
194 | introduced. | |
195 | ||
196 | The file can be read by the | |
197 | <pre> | |
198 | pythia.readFile(fileName); | |
199 | </pre> | |
200 | method. The file can freely mix commands to the <code>Settings</code> | |
201 | and <code>ParticleData</code> classes, and so is preferable. Lines with | |
202 | settings are handled by calls to the | |
203 | <code>pythia.settings.readString(string)</code> method. Again, an optional | |
204 | second argument <code>false</code> allows you to switch off warning | |
205 | messages for unknown variables. | |
206 | </li> | |
207 | ||
208 | <p/> <li> | |
209 | In the <code>Pythia init</code> call, many of the various other program | |
210 | elements are initialized, making use of the current values in the database. | |
211 | Once initialized, the common <code>Settings</code> database is likely not | |
212 | consulted again by these routines. It is therefore not productive to do | |
213 | further changes in mid-run: at best nothing changes, at worst you may | |
214 | set up inconsistencies. | |
215 | ||
216 | <p/> | |
217 | A routine <code>reInit(fileName)</code> is provided, and can be used to | |
218 | zero all the maps and reinitialize from scratch. Such a call might be | |
219 | required if several <code>Pythia</code> objects are created in the same run, | |
220 | and requested to have different values - by default the <code>init()</code> | |
221 | call is only made the first time. However, a more economical solution | |
222 | is then offered by <code>resetAll()</code>, which sets all variables to | |
223 | their default values. | |
224 | </li> | |
225 | ||
226 | <p/> <li> | |
227 | You may at any time obtain a listing of all variables in the | |
228 | database by calling | |
229 | <pre> | |
230 | pythia.settings.listAll(); | |
231 | </pre> | |
232 | The listing is strictly alphabetical, which at least means that names | |
233 | from the same file are kept together, but otherwise may not be so | |
234 | well-structured: important and unimportant ones will appear mixed. | |
235 | A more relevant alternative is | |
236 | <pre> | |
237 | pythia.settings.listChanged(); | |
238 | </pre> | |
239 | where you will only get those variables that differ from their | |
240 | defaults. Or you can use | |
241 | <pre> | |
242 | pythia.settings.list("string"); | |
243 | </pre> | |
244 | where only those variables with names that contain the string | |
245 | (case-insensitive match) are listed. Thus, with a string | |
246 | <code>shower</code>, the shower-related variables would be shown. | |
247 | </li> | |
248 | ||
249 | <p/> <li> | |
250 | The above listings are in a tabular form that cannot be read | |
251 | back in. Assuming you want to save all changed settings (maybe because | |
252 | you read in changes from several files), you can do that by calling | |
253 | <pre> | |
254 | pythia.settings.writeFile(fileName); | |
255 | </pre> | |
256 | This file could then directly be read in by | |
257 | <code>readFile(fileName)</code> in a subsequent (identical) run. | |
258 | A second argument <code>true</code> would print all settings, not | |
259 | only the changed ones. Further, the first argument can be replaced by | |
260 | (a reference to) an <code>ostream</code>, by default <code>cout</code>. | |
261 | </li> | |
262 | </ol> | |
263 | ||
264 | </chapter> | |
265 | ||
266 | <!-- Copyright (C) 2008 Torbjorn Sjostrand --> |