[1] | 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 --> |
---|