--- /dev/null
+<chapter name="Tunes">
+
+<h2>Tunes</h2>
+
+Since some physics aspects cannot be derived from first principles,
+this program contains many parameters that represent a true
+uncertainty in our understanding of nature. Particularly afflicted
+are the areas of hadronization and multiparton interactions, which both
+involve nonperturbative QCD physics.
+
+<p/>
+Technically, PYTHIA parameters can be varied independently of each
+other, but the physical requirement of a sensible description of a set
+of data leads to correlations and anticorrelations between the
+parameters. Hence the need to produce tunes, not of one parameter at
+a time, but simultaneously for a group of them. A well-known (separate)
+such example is parton densities, where combined tunes to a wide range
+of data have been produced, that can then be obtained prepackaged.
+
+<p/>
+Given the many PYTHIA parameters to be tuned, it is convenient to
+divide the task into subtasks. Firstly, if we assume jet universality,
+hadronization and final-state parton showers should be tuned to
+<ei>e^+e^-</ei> annihilation data, notably from LEP1, since this
+offers the cleanest environment. Secondly, with such parameters fixed,
+hadron collider data should be studied to pin down multiparton interactions
+and other further aspects, such as initial-state radiation. Ideally this
+would be done separately for diffractive and non-diffractive events,
+although it is not possible to have a clean separation. (Thirdly
+would come anything else, such as physics with photon beams, which
+involve further parameters, but that is beyond the current scope.)
+
+<p/>
+The first step in this program has now been taken, with a tune to LEP1
+data by Hendrik Hoeth, using the Rivet + Professor framework. Starting
+with version 8.125 it defines the default values for hadronization
+parameters and timelike showers.
+
+<p/>
+The situation is more complicated for hadronic interactions in general
+and multiparton interactions in particular, where PYTHIA 8 is more
+different from PYTHIA 6, and therefore more work is needed. Specifically,
+it is <i>not</i> possible to "port" a PYTHIA 6 tune to PYTHIA 8.
+
+<p/>
+A first simple tune, appropriately called "Tune 1", became default
+starting with version 8.127. It was noted, in particular by Hendrik
+Hoeth, that this tune had a tension between parameters needed to
+describe minimum-bias and underlying-event activity. Therefore some
+further physics features were introduced in the code itself
+<ref>Cor10a</ref>, which were made default as of 8.140. This version
+also included two new tunes, 2C and 2M, based on the CTEQ 6L1 and the
+MRST LO** PDF sets, respectively. These have been made by hand, as a
+prequel to complete Professor-style tunings.
+
+<p/>
+The very first data to come out of the LHC showed a higher rapidity
+plateau than predicted for current PYTHIA 6 tunes, also for the lower
+energies. This may suggest some tension in the data. Two alternatives,
+3C and 3M, were produced by a few brute-force changes of 2C and 2M.
+These were introduced in 8.140, but discontinued in 8.145 in favour of
+the new 4C tune, that is based on a more serious study of some early
+LHC data, see <ref>Cor10a</ref>. Following the comparative studies in
+<ref>Buc11</ref>, which independently confirmed a reasonable agreement
+with LHC data, tune 4C was made the default as of 8.150. A variant is
+tune 4Cx, where the Gaussian matter profile has an <ei>x</ei>-dependent
+width <ref>Cor11</ref>.
+
+<p/>
+Several ATLAS tunes have now been included, obtained with different PDFs
+and with different emphasis on minimum-bias and underlying-event data
+<ref>ATL12</ref>. These typically require LHAPDF to be linked, but this
+can be avoided in cases where the same PDF set is implemented internally.
+
+<p/>
+Central diffraction is a recent addition to the "soft QCD" process palette,
+and is thus not yet included in tunes; indeed its cross section is actively
+zeroed. You can switch it back on <i>after</i> you have selected your tune,
+with <code>SigmaTotal:zeroAXB = off</code>. But note that, since the
+total cross section is assumed unchanged, the minbias cross section
+is reduced and thus also the MPI machinery affected, even if effects
+should not be big (for a small central diffractive cross section).
+
+<p/>
+Note that comparisons with data also require that other aspects agree,
+such as that decay chains are stopped at an agreed-on level. For instance,
+in the ATLAS tunes all particles with a lifetime above 10 mm
+are considered stable, <code>ParticleDecays:limitTau0 = on</code>,
+<code>ParticleDecays:tau0Max = 10</code>. We have chosen not to
+include this as part of the tune settings itself, since the tune as
+such could still be used with any other choice of stable and
+unstable particles.
+
+<p/>
+Further comparisons have been posted on the
+<a href="http://mcplots.cern.ch/">MCPLOTS</a> pages.
+They have been produced with help of the
+<a href="http://projects.hepforge.org/rivet/">Rivet</a> package
+<ref>Buc10</ref>.
+
+<p/>
+In the future we hope to see further PYTHIA 8 tunes appear. Like with
+parton distributions, there is likely to be several tunes, because
+different sets of data will pull in different directions, by imperfections
+in the model or in the data, and by differences in the chosen
+tuning strategies. We therefore propose to collect some of these tunes
+here, in a prepackaged form. Of course, in all cases it is a matter
+of setting values for parameters already defined elsewhere, so the
+tunes offer no new functionality, only a more convenient setup.
+
+<p/>
+You should be aware that the evolution of the program will not guarantee
+complete backwards compatibility between versions. Most obviously this
+concerns bug fixes. But also for some other major changes, like the
+introduction of the new diffractive machinery, the default behaviour
+of old tunes has been changed retroactively. (Which should be fine for
+diffraction, since previous tunes were not based on data strongly
+influenced by diffraction.)
+
+<p/>
+The setup of the tunes is special, in that the choice of a tune forces
+the change of several different flags, modes and parameters. Furthermore
+a design principle has been that it should be possible to start out
+from a tune and then change a few of its settings. This gives power
+and flexibility at the expense of requiring a more careful ordering
+of commands. We therefore here sketch the order in which operations
+are carried out.
+<ol>
+<li>The constructor of a <code>Pythia</code> instance will read in
+all settings, and initialize them with their default values.
+</li>
+<li>At the end of this operation, the <code>Tune:ee</code> and
+<code>Tune:pp</code> modes (see further below) are checked. If either
+of them are positive the methods <code>Settings::initTuneEE(...)</code>
+and <code>Settings::initTunePP(...)</code>, respectively, are called
+to overwrite the whole collection of settings in the relevant tune.
+Zero (or negative) means that nothing will be done.
+</li>
+<li>After the <code>Pythia</code> constructor all the relevant values
+for the default tune(s) have thus been set up.
+</li>
+<li>You as a user can now start to overwrite the values at will,
+using <code>Pythia::readFile(...)</code> to read a configuration file,
+or a list of <code>Pythia::readString(...)</code> commands,
+or the lower-level <code>Settings</code> methods. All changes
+are made in the order in which the commands are encountered during
+the execution. A given variable can be changed multiparton times,
+but it is the latest change that sets the current value.
+</li>
+<li>The two <code>Tune:ee</code> and <code>Tune:pp</code> modes can also
+be changed in exactly the same way as described for all other settings
+above. Unique for them, however, is that when one of them is encountered
+it also initiates a call to the <code>initTuneEE(...)</code> or
+<code>initTunePP(...)</code> method, respectively. In such cases all
+settings affected by the <ei>e^+e^-</ei> or <ei>pp/ppbar</ei> tune
+are first reset to the default values (the <code>-1</code> options)
+and thereafter the relevant tune is set up.
+</li>
+<li>It is possible to mix commands of type 4 and 5 in any order; it
+is always the last change that counts. That is, any changes you have
+made to variables of a tune <i>before</i> a <code>Tune:ee</code> or
+<code>Tune:pp</code> command are overwritten by it, while variables
+you set <i>after</i> will overwrite the tune values. As a rule,
+therefore, you want to begin with the tune choice, and thereafter
+modify only a small part of its settings.
+</li>
+<li>Needless to say, the flexibility can lead to unwanted setups if
+you do not exercise some discipline. It is therefore recommended that
+you always check the listing obtained with
+<code>Pythia::settings.listChanged()</code> to confirm that the
+final set of changes is the intended one.
+</li>
+</ol>
+
+<modepick name="Tune:ee" default="0" min="-1" max="3">
+Choice of tune to <ei>e^+e^-</ei> data, mainly for the hadronization
+and timelike-showering aspects of PYTHIA. You should study the
+<code>Settings::initTuneEE(...)</code> method to find exactly which
+are the settings for the respective tune.
+<option value="-1">reset all values that are affected by any of the
+<ei>e^+e^-</ei> tunes to the default values. This option can be used
+on its own, but is also automatically used as a first step for either
+of the positive tune values below, to undo the effect of previous tune
+settings.
+</option>
+<option value="0">no values are overwritten during the initial setup,
+step 2 above. Note that changing to <code>0</code> in the user code
+has no effect; if you want to restore the individual settings you
+should instead use <code>-1</code>.
+</option>
+<option value="1">the original PYTHIA 8 parameter set, based on some
+very old flavour studies (with JETSET around 1990) and a simple tune
+<ei>of alpha_strong</ei> to three-jet shapes to the new
+<ei>pT</ei>-ordered shower. These were the default values before
+version 8.125.
+</option>
+<option value="2">a tune by Marc Montull to the LEP 1 particle
+composition, as published in the RPP (August 2007). No related (re)tune
+to event shapes has been performed, however.
+</option>
+<option value="3">a tune to a wide selection of LEP1 data by Hendrik
+Hoeth within the Rivet + Professor framework, both to hadronization and
+timelike-shower parameters (June 2009). These are the default values
+starting from version 8.125, so currently there is no need for this
+option.
+</option>
+</modepick>
+
+<flag name="Tune:preferLHAPDF" default="on">
+Tunes made by experimental collaborations typically use the LHAPDF
+package to obtain their PDF values, and so PYTHIA has to be linked
+accordingly. For PDFs implemanted natively in PYTHIA it is possible
+to use the respective tunes, without having to link to LHAPDF, if you
+set <code>Tune:preferLHAPDF = off</code> <i>before</i> the
+<code>Tune:pp</code> choice.
+</flag>
+
+<modepick name="Tune:pp" default="5" min="-1" max="11">
+Choice of tune to <ei>pp/ppbar</ei> data, mainly for the
+initial-state-radiation, multiparton-interactions and beam-remnants
+aspects of PYTHIA. Note that the previous crude (non-)tunes
+3C and 3M are removed as of 8.145, superseded by the 4C tune.
+You should study the <code>Settings::initTunePP(...)</code> method
+to find exactly which are the settings for the respective tune.
+<option value="-1">reset all values that are affected by any of the
+<ei>pp/ppbar</ei> tunes to the default values. This option can be used
+on its own, but is also automatically used as a first step for either
+of the positive tune values below, to undo the effect of previous tune
+settings.
+</option>
+<option value="0">no values are overwritten during the initial setup,
+step 2 above. Note that changing to <code>0</code> in the user code
+has no effect; if you want to restore the individual settings you
+should instead use <code>-1</code>.
+</option>
+<option value="1">default used up to version 8.126, based on
+some early and primitive comparisons with data.
+</option>
+<option value="2">"Tune 1", default in 8.127 - 8.139, based on some
+data comparisons by Peter Skands. Largely but not wholly overlaps
+with the default option 0.
+</option>
+<option value="3">"Tune 2C", introduced with 8.140 <ref>Cor10a</ref>.
+It uses the CTEQ 6L1 PDF, and is intended to give good agreement with
+much of the published CDF data.
+</option>
+<option value="4">"Tune 2M", introduced with 8.140 <ref>Cor10a</ref>.
+It is uses the MRST LO** PDF, which has a momentum sum somewhat above
+unity, which is compensated by a smaller <ei>alpha_s</ei> than in the
+previous tune. Again it is intended to give good agreement with much of
+the published CDF data.
+</option>
+<option value="5">"Tune 4C", new tune, introduced with 8.145
+<ref>Cor10a</ref>. Starts out from tune 2C, but with a reduced cross
+section for diffraction, plus modified multiparton interactions parameters
+to give a higher and more rapidly increasing charged pseudorapidity
+plateau, for better agreement with some early key LHC numbers.
+See also the comparative study in <ref>Buc11</ref>.
+</option>
+<option value="6">"Tune 4Cx", based on tune 4C, but using the x-dependent
+matter profile, <code>MultipartonInteractions:bProfile = 4</code> and an
+increased <code>MultipartonInteractions:pT0Ref</code> <ref>Cor11</ref>.
+</option>
+<option value="7">"ATLAS MB Tune A2-CTEQ6L1", a minimum-bias tune based
+on tune 4Cx, but without rapidity-ordered spacelike emissions
+<ref>ATL12</ref>. Uses CTEQ 6L1, by default from LHAPDF.
+</option>
+<option value="8">"ATLAS MB Tune A2-MSTW2008LO", as above,
+but uses MSTW 2008 LO, by default from LHAPDF.
+</option>
+<option value="9">"ATLAS UE Tune AU2-CTEQ6L1", an underlying-event tune
+based on tune 4Cx, but without rapidity-ordered spacelike emissions
+<ref>ATL12</ref>. Uses CTEQ 6L1, by default from LHAPDF.
+</option>
+<option value="10">"ATLAS UE Tune AU2-MSTW2008LO", as above,
+but uses MSTW 2008 LO, by default from LHAPDF.
+</option>
+<option value="11">"ATLAS UE Tune AU2-CT10", as above,
+but uses CT 10, which is not currently implemented in PYTHIA,
+so you must link LHAPDF.
+</option>
+<option value="12">"ATLAS UE Tune AU2-MRST2007LO*", as above,
+but uses MRST 2007 LO*, by default from LHAPDF.
+</option>
+<option value="13">"ATLAS UE Tune AU2-MRST2007LO**", as above,
+but uses MRST 2007 LO**, by default from LHAPDF.
+</option>
+</modepick>
+
+</chapter>
+
+<!-- Copyright (C) 2012 Torbjorn Sjostrand -->