+++ /dev/null
-<chapter name="The Settings Scheme">
-
-<h2>The Settings Scheme</h2>
-
-The <code>Settings</code> class keeps track of all the flags, modes,
-parameters and words used during the event generation. As such, it
-serves all the <code>Pythia</code> program elements from one central
-repository. Accessing it allows the user to modify the generator
-behaviour.
-
-<p/>
-Each <code>Pythia</code> object has a public member <code>settings</code>
-of the <code>Settings</code> class. Therefore you access the
-settings methods as <code>pythia.settings.command(argument)</code>,
-assuming that <code>pythia</code> is an instance of the <code>Pythia</code>
-class. Further, for the most frequent user tasks, <code>Pythia</code>
-methods have been defined, so that <code>pythia.command(argument)</code>
-would work, see further below.
-
-<p/>
-The central section on this page is the Operation one. The preceding
-concepts section is there mainly to introduce the basic structure and
-the set of properties that can be accessed. The subsequent sections
-provide a complete listing of the existing public methods, which most
-users probably will have little interaction with.
-
-<h3>Concepts</h3>
-
-We distinguish four kinds of user-modifiable variables, by the way
-they have to be stored:
-<ol>
-<li>Flags are on/off switches, and are stored as <code>bool</code>.</li>
-<li>Modes corresponds to a finite enumeration of separate options,
- and are stored as <code>int</code>.</li>
-<li>Parameters take a continuum of values, and are stored as
-<code>double</code>. The shorthand notation parm is used in the C++
-code and XML tags, so that all four kinds are represented by
-four-letter type names.</li>
-<li>Words are simple character strings and are stored as
-<code>string</code>. No blanks or double quotation marks (") may
-appear inside a word, the former to simplify parsing of an input file
-and the latter not to cause conflicts with XML attribute delimiters.
-Currently the main application is to store file names.</li>
-</ol>
-
-<p/>
-In general, each variable stored in <code>Settings</code> is associated
-with four kinds of information:
-<ul>
-<li>The variable name, of the form <code>class:name</code>
-(or <code>file:name</code>, usually these agree), e.g.
-<code>TimeShower:pTmin</code>. The class/file part usually identifies
-the <code>.xml</code> file where the variable is defined, and the part of
-the program where it is used, but such a connection cannot be strictly
-upheld, since e.g. the same variable may be used in a few different
-cases (even if most of them are not).</li>
-<li>The default value, set in the original declaration, and intended
-to represent a reasonable choice.</li>
-<li>The current value, which differs from the default when the user so
-requests.</li>
-<li>An allowed range of values, represented by meaningful
-minimum and maximum values. This has no sense for a <code>flag</code>
-or a <code>word</code> (and is not used there), is usually rather
-well-defined for a <code>mode</code>, but less so for a <code>parm</code>.
-Often the allowed range exaggerates the degree of our current knowledge,
-so as not to restrict too much what the user can do. One may choose
-not to set the lower or upper limit, in which case the range is
-open-ended.</li>
-</ul>
-
-<p/>
-Technically, the <code>Settings</code> class is implemented with the
-help of four separate maps, one for each kind of variable, with the
-variable <code>name</code> used as key.
-
-<h3>Operation</h3>
-
-The normal flow of setting values is:
-
-<ol>
-
-<p/> <li>
-When a <code>Pythia</code> object <code>pythia </code>is created,
-the member <code>pythia.settings</code> is asked to scan the files
-listed in the <code>Index.xml</code> file in the <code>xmldoc</code>
-subdirectory.
-
-<p/>
-In all of the files scanned, lines beginning with
-<code><flag</code>, <code><mode</code>, <code><parm</code>
-or <code><word</code> are identified, and the information on
-such a line is used to define a new flag, mode, parameter or word.
-To exemplify, consider a line
-<pre>
-<parm name="TimeShower:pTmin" default="0.5" min="0.1" max="2.0">
-</pre>
-which appears in the <code>TimeShower.xml</code> file, and there
-defines a parameter <code>TimeShower:pTmin</code> with default value
-0.5 GeV and allowed variation in the range 0.1 - 2.0 GeV. The min
-and max values are optional.
-<note>Important:</note> the values in the <code>.xml</code> files should
-not be changed, except by the PYTHIA authors. Any changes should be
-done with the help of the methods described below.
-</li>
-
-<p/> <li>
-Between the creation of the <code>Pythia</code> object and the
-<code>init</code> call for it, you may use several alternative
-methods to modify some of the default values.
-
-<p/>
-a) Inside your main program you can directly set values with
-<pre>
- pythia.readString(string)
-</pre>
-where both the variable name and the value are contained inside
-the character string, separated by blanks and/or a =, e.g.
-<pre>
- pythia.readString("TimeShower:pTmin = 1.0");
-</pre>
-The match of the name to the database is case-insensitive. Names
-that do not match an existing variable are ignored. A warning is
-printed, however. Strings beginning with a non-alphanumeric character,
-like # or !, are assumed to be comments and are not processed at all.
-Values below the minimum or above the maximum are set at
-the respective border. For <code>bool</code> values, the following
-notation may be used interchangeably:
-<code>true = on = yes = ok = 1</code>, while everything else gives
-<code>false</code> (including but not limited to
-<code>false</code>, <code>off</code>, <code>no</code> and 0).<br/>
-
-<p/>
-b) The <code>Pythia</code> <code>readString(string)</code> method
-actually does not do changes itself, but sends on the string either
-to the <code>Settings</code> class or to <code>ParticleData</code>.
-The former holds if the string begins with a letter, the latter
-if it begins with a digit. If desired, it is possible to communicate
-directly with the corresponding <code>Settings</code> method:
-<pre>
- pythia.settings.readString("TimeShower:pTmin = 1.0");
-</pre>
-In this case, changes intended for <code>ParticleData</code>
-would not be understood.
-
-<p/>
-c) Underlying the <code>settings.readString(string)</code> method are
-the settings-type-sensitive commands in the <code>Settings</code>, that
-are split by names containing <code>flag</code>, <code>mode</code>,
-<code>parm</code> or <code>word</code>. Thus, the example now reads
-<pre>
- pythia.settings.parm("TimeShower:pTmin", 1.0);
-</pre>
-Such a form could be convenient e.g. if a parameter is calculated
-at the beginning of the main program, and thus is available as a
-variable rather than as a character string.
-Note that Boolean values must here be given as <code>true</code> or
-<code>false</code> i.e. there is less flexibility than with the
-previous methods.
-
-<p/>
-At the same level, there are several different methods available.
-These are included in the full description below, but normally the user
-should have no need for them.
-
-<p/>
-d) A simpler and more useful way is to collect all your changes
-in a separate file, with one line per change, e.g.
-<pre>
- TimeShower:pTmin = 1.0
-</pre>
-Each line is read in as a string and processed with the methods already
-introduced.
-
-The file can be read by the
-<pre>
- pythia.readFile(fileName);
-</pre>
-method (or an <code>istream</code> instead of a <code>fileName</code>).
-The file can freely mix commands to the <code>Settings</code> and
-<code>ParticleData</code> classes, and so is preferable. Lines with
-settings are handled by calls to the
-<code>pythia.settings.readString(string)</code> method.
-</li>
-
-<p/> <li>
-In the <code>pythia.init(...)</code> call, many of the various other program
-elements are initialized, making use of the current values in the database.
-Once initialized, the common <code>Settings</code> database is likely not
-consulted again by these routines. It is therefore not productive to do
-further changes in mid-run: at best nothing changes, at worst you may
-set up inconsistencies.
-
-<p/>
-A routine <code>reInit(fileName)</code> is provided, and can be used to
-zero all the maps and reinitialize them from scratch. Such a call might be
-useful if several subruns are to be made with widely different parameter
-sets - normally the maps are only built from scratch once, namely when the
-<code>Pythia()</code> object is created. A more economical alternative is
-offered by <code>resetAll()</code>, however, which sets all variables back
-to their default values.
-</li>
-
-<p/> <li>
-You may at any time obtain a listing of all variables in the
-database by calling
-<pre>
- pythia.settings.listAll();
-</pre>
-The listing is strictly alphabetical, which at least means that names
-from the same file are kept together, but otherwise may not be so
-well-structured: important and unimportant ones will appear mixed.
-A more relevant alternative is
-<pre>
- pythia.settings.listChanged();
-</pre>
-where you will only get those variables that differ from their
-defaults. Or you can use
-<pre>
- pythia.settings.list("string");
-</pre>
-where only those variables with names that contain the string
-(case-insensitive match) are listed. Thus, with a string
-<code>shower</code>, the shower-related variables would be shown.
-</li>
-
-<p/> <li>
-The above listings are in a tabular form that cannot be read
-back in. Assuming you want to save all changed settings (maybe because
-you read in changes from several files), you can do that by calling
-<pre>
- pythia.settings.writeFile(fileName);
-</pre>
-This file could then directly be read in by
-<code>readFile(fileName)</code> in a subsequent (identical) run.
-Some variants of this command are listed below.
-</li>
-</ol>
-
-<h3>Methods</h3>
-
-The complete list of methods and arguments is as follows. Most of the
-ones of interest to the user have already been mentioned above.
-Others can be used, but the same functionality is better achieved
-by higher-level routines. Some are part of the internal machinery,
-and should not be touched by user.
-
-<p/>
-Note that there is no <code>Settings::readFile(...)</code> method.
-The intention is that you should use <code>Pythia::readFile(...)</code>.
-It parses and decides which individual lines should be sent on to
-<code>Settings::readString(...)</code>.
-
-<method name="Settings::Settings()">
-the constructor, which takes no arguments. Internal.
-</method>
-
-<method name="bool Settings::initPtr(Info* infoPtrIn)">
-initialize pointer to error-message database. Internal.
-</method>
-
-<method name="bool Settings::init(string
-startFile = "../xmldoc/Index.xml", bool append = false,
-ostream& os = cout)">
-read in the settings database.
-<argument name="startFile" default=""../xmldoc/Index.xml"">
-read in the settings from all the files listed in this file, and
-assumed to be located in the same subdirectory.
-</argument>
-<argument name="append" default="false">
-By default nothing is done if the method has already been called once.
-If true the further settings read in are added to the current database.
-</argument>
-<argument name="os" default="cout">
-stream for error printout.
-</argument>
-<note>Note:</note> The method returns false if it fails.
-</method>
-
-<method name="bool Settings::reInit(string
-startFile = "../xmldoc/Index.xml", ostream& os = cout)">
-overwrite the existing database.
-<argument name="startFile" default=""../xmldoc/Index.xml"">
-read in the settings from all the files listed in this file, and
-assumed to be located in the same subdirectory.
-</argument>
-<argument name="os" default="cout">
-stream for error printout.
-</argument>
-<note>Note:</note> The method returns false if it fails.
-</method>
-
-<method name="bool Settings::readString(string line,
-bool warn = true, ostream& os = cout)">
-read in a string, and change the relevant quantity in the database.
-It is normally used indirectly, via
-<code>Pythia::readString(...)</code> and
-<code>Pythia::readFile(...)</code>.
-<argument name="line">
-the string to be interpreted as an instruction.
-</argument>
-<argument name="warn" default="true">
-write a warning message or not whenever the instruction does not make
-sense, e.g. if the variable does not exist in the databases.
-</argument>
-<argument name="os" default="cout">
-stream for error printout.
-</argument>
-<note>Note:</note> the method returns false if it fails to
-make sense out of the input string.
-</method>
-
-<method name="bool Settings::writeFile(string toFile,
-bool writeAll = false)">
-</method>
-<methodmore name="bool Settings::writeFile(ostream& os = cout,
-bool writeAll = false)">
-write current settings to a file or to an <code>ostream</code>.
-<argument name="toFile, os">
-file or stream on which settings are written.
-</argument>
-<argument name="writeAll" default="false">
-normally only settings that have been changed are written,
-but if true then all settings are output.
-</argument>
-<note>Note:</note> the method returns false if it fails.
-</methodmore>
-
-<method name="void Settings::listAll(ostream& os = cout)">
-</method>
-<methodmore name="void Settings::listChanged(ostream& os = cout)">
-</methodmore>
-<methodmore name="void Settings::list(string match,
-ostream& os = cout)">
-list all or changed settings, or a group of them.
-<argument name="match">
-list all those settings where the name contains
-the <code>match</code> (sub)string (case-insensitive).
-</argument>
-<argument name="os" default="cout">
-output stream for the listing.
-</argument>
-</methodmore>
-
-<method name="void Settings::resetAll()">
-reset all current values to their defaults.
-</method>
-
-<method name="bool Settings::isFlag(string key)">
-</method>
-<methodmore name="bool Settings::isMode(string key)">
-</methodmore>
-<methodmore name="bool Settings::isParm(string key)">
-</methodmore>
-<methodmore name="bool Settings::isWord(string key)">
-return true if an entry of the given name and kind
-exists, else false.
-</methodmore>
-
-<method name="void Settings::addFlag(string key, bool default)">
-</method>
-<methodmore name="void Settings::addMode(string key,
-int default, bool hasMin, bool hasMax, int min, int max)">
-</methodmore>
-<methodmore name="void Settings::addParm(string key,
-double default, bool hasMin, bool hasMax, double min, double max)">
-</methodmore>
-<methodmore name="void Settings::addWord(string key,
-string default)">
-add an entry of the respective kind to the database. The name and default
-value always has to be supplied, for <code>Mode</code> and
-<code>Word</code> additionally if lower and/or upper limits are to be
-imposed and, if so, what those limit are.
-</methodmore>
-
-<method name="bool Settings::flag(string key)">
-</method>
-<methodmore name="int Settings::mode(string key)">
-</methodmore>
-<methodmore name="double Settings::parm(string key)">
-</methodmore>
-<methodmore name="string Settings::word(string key)">
-return the current value of the respective setting. If the name
-does not exist in the database, a value <code>false</code>,
-<code>0</code>, <code>0.</code> and <code>" "</code>
-is returned, respectively.
-</methodmore>
-
-<method name="void Settings::flag(string key, bool now)">
-</method>
-<methodmore name="void Settings::mode(string key, int now)">
-</methodmore>
-<methodmore name="void Settings::parm(string key, double now)">
-</methodmore>
-<methodmore name="void Settings::word(string key, string now)">
-change the current value of the respective setting to the provided
-new value. If lower or upper limits have been set, input values
-outside the allowed range are reinterpreted as being a the nearest
-limit.
-</methodmore>
-
-<method name="void Settings::forceMode(string key, int now)">
-</method>
-<methodmore name="void Settings::forceParm(string key, double now)">
-as above, but do not check lower and upper limits, so that the current
-value can be put outside the intended borders.
-</methodmore>
-
-<method name="void Settings::resetFlag(string key)">
-</method>
-<methodmore name="void Settings::resetMode(string key)">
-</methodmore>
-<methodmore name="void Settings::resetParm(string key)">
-</methodmore>
-<methodmore name="void Settings::resetWord(string key)">
-reset the current value to the default one.
-</methodmore>
-
-</chapter>
-
-<!-- Copyright (C) 2010 Torbjorn Sjostrand -->
git://git.uio.no / u / mrichter / AliRoot.git / blobdiff