Main-Program Settings
Introduction
The main program is up to the user to write. However, sample main
programs are provided, as documented further down on this page. In one
such class of programs, key settings of the run are read in from a
"cards file". These commands may be of two types
(a) instructions directly to Pythia
, like which
processes to generate, and
(b) instructions to the main program for what it should do,
like how many events to generate, i.e. how many times
pythia.next()
should be called.
In principle these two kinds could be kept completely separate.
However, to make life simpler, a number of useful main-program
settings are defined on this page, so that they are recognized by
the Settings
machinery. They can thus be put among
the other cards without distinction. It is up to you to decide which
ones, if any, you actually want to use when you write your main program.
For convenience, the ones in the first section below, and some in the
second section, can also be interpreted directly by Pythia
,
while the subsequent ones really have to be used in your main program.
Once you have used the pythia.readFile(fileName)
method to
read in the cards file, you can interrogate the Settings
database to make the values available in your main program. A slight
complication is that you need to use a different Settings
method for each of the four possible return types that you want to
extract. To save some typing the same method names are found directly
in the Pythia
class, and just send on to the
Settings
ones to do the job, e.g.
bool showCS = pythia.flag("Main:showChangedSettings");
int nEvent = pythia.mode("Main:numberOfEvents");
double eCM = pythia.parm("Main:eCM");
string file = pythia.word("Main:allSettingsFile");
Incoming beams
Normally the identities and energies of the two incoming beam particles
are given by the arguments of the various forms of the init
call. These settings can be stored in an input "cards" file, in the
following variables, and thereafter read in the user-written main program.
As a shortcut, an init()
call with no arguments will make use
of the beam values directly. That is, if nothing is set, you will default
to LHC at the nominal energy. Usage is purely optional.
mode
Main:idBeamA
(default = 2212
)
The PDG id
code for the first incoming particle.
mode
Main:idBeamB
(default = 2212
)
The PDG id
code for the second incoming particle.
flag
Main:inCMframe
(default = on
)
Assume collisions occur in the CM frame.
parm
Main:eCM
(default = 14000.
; minimum = 10.
)
Collision CM energy, to be given if Main:inCMframe
is on.
parm
Main:eBeamA
(default = 7000.
; minimum = 0.
)
The energy of the first incoming particle, moving in the
+z direction, to be given if Main:inCMframe
is off. If the particle energy is smaller than its mass
it is assumed to be at rest.
parm
Main:eBeamB
(default = 7000.
; minimum = 0.
)
The energy of the second incoming particle, moving in the
-z direction, to be given if Main:inCMframe
is off. If the particle energy is smaller than its mass
it is assumed to be at rest.
word
Main:LHEF
(default = void
)
The name of a Les Houches Event File. If you initialize with
init()
without any arguments, and Main:LHEF
has been set differently from its default value void
, the
initialization and subsequent run is based on the information stored
in this file, overriding the beam-parameter input above.
Currently there are no provisions for arbitrary beam directions,
but you can always rotate and boost the final
event record appropriately.
For instance, consider two beams of equal energy but with a slight
acollinearity: they are both an angle chi away from
the +-z axis in the +x direction, such that the
total acollinearity is 2 chi. Then a boost beta_x = chi,
achieved by pythia.event.bst( chi, 0., 0.)
, moves
the event to the correct frame.
Subruns
You can use subruns to carry out
several tasks in the same run. In that case you will need repeated
instances of the first setting below in your command file, and could
additionally use the second and third as well.
mode
Main:subrun
(default = -999
; minimum = 0
)
The number of the current subrun, a non-negative integer, put as
first line in a section of lines to be read for this particular subrun.
flag
Main:LHEFskipInit
(default = off
)
If you read several Les Houches Event Files that you want to see
considered as one single combined event sample you can set this flag
on
after the first subrun to skip (most of) the
(re-)initialization step.
mode
Main:numberOfSubruns
(default = 0
)
The number of subruns you intend to use in your current run.
Unlike the two settings above, Pythia
itself will not
intepret this number, but you could e.g. have a loop in your main
program to loop over subruns from 0 through
numberOfSubruns - 1
.
Run settings
Here further settings related to how many events to generate and whether
to print some information on data used in run. Again these variables
can be set in an input "cards" file, and thereafter read out an used
in the user-written main program. Usage is purely optional, but may help
you reduce the need to recompile your main program.
mode
Main:numberOfEvents
(default = 1000
; minimum = 0
)
The number of events to be generated.
mode
Main:numberToList
(default = 2
; minimum = 0
)
The number of events to list.
mode
Main:timesToShow
(default = 50
; minimum = 0
)
Print the number of events generated so far, this many times,
i.e. once every numberOfEvents/numberToShow
events.
mode
Main:timesAllowErrors
(default = 10
)
Allow this many times that pythia.next()
returns false,
i.e. that an event is flawed, before aborting the run.
flag
Main:showChangedSettings
(default = on
)
Print a list of the changed flag/mode/parameter/word settings.
flag
Main:showAllSettings
(default = off
)
Print a list of all flag/mode/parameter/word settings.
Warning: this will be a long list.
mode
Main:showOneParticleData
(default = 0
; minimum = 0
)
Print particle and decay data for the particle with this particular
identity code. Default means that no particle is printed.
flag
Main:showChangedParticleData
(default = off
)
Print a list of particle and decay data for those particles
that were changed (one way or another).
flag
Main:showChangedResonanceData
(default = off
)
In the previous listing also include the resonances that are
initialized at the beginning of a run and thus get new particle
data, even if these may well agree with the default ones.
Warning: this will be a rather long list.
flag
Main:showAllParticleData
(default = off
)
Print a list of all particle and decay data.
Warning: this will be a long list.
flag
Main:writeChangedSettings
(default = off
)
Write a file with the changed flag/mode/parameter/word settings, in
a format appropriate to be read in at the beginning of a new
run, using the pythia.readFile(fileName)
method.
word
Main:changedSettingsFile
(default = currentSettings.cmnd
)
The name of the file to which the changed flag/mode/parameter/word
settings are written if Main:writeChangedSettings
is on.
flag
Main:writeAllSettings
(default = off
)
Write a file with all flag/mode/parameter/word settings, in
a format appropriate to be read in at the beginning of a new
run, using the pythia.readFile(fileName)
method.
word
Main:allSettingsFile
(default = allSettings.cmnd
)
The name of the file to which a flag/mode/parameter/word
settings are written if Main:writeAllSettings
is on.
flag
Main:showAllStatistics
(default = off
)
Print all available statistics or only the minimal set at the end
of the run.
Sample main programs
To help exemplify what a main program could look like, a few simple
examples are provided:
main01.cc
: a simple study of the charged multiplicity
for jet events at the LHC. (Brief example given in talks.)
main02.cc
: a simple study of the pT spectrum
of Z bosons at the Tevatron. (Brief example given in talks.)
main03.cc
: a simple single-particle analysis of jet
events, where input is set by main03.cmnd
"cards file".
main04.cc
: a simple study of several different kinds
of events, with the choice to be made in the main04.cmnd
"cards file".
main05.cc
: generation of QCD jet events at the LHC,
with jet analysis using the CellJet
cone-jet finder.
main06.cc
: tests of cross sections for elastic and
diffractive topologies, using main06.cmnd
to pick process.
main07.cc
: tests of cross sections for minimum-bias
events, using main07.cmnd
to pick options.
main08.cc
: generation of the QCD jet cross section
by splitting the run into subruns, each in its own pT bin,
and adding the results properly reweighted. Two options, with limits
set either in the main program or by subrun specification in the
main08.cmnd
file.
main09.cc
: generation of LEP1 hadronic events, i.e.
e^+e^- -> gamma*/Z^0 -> q qbar, with charged multiplicity,
sphericity, thrust and jet analysis.
main10.cc
: illustration how userHooks can be used
interact directly with the event-generation process.
main11.cc
: generation of two predetermined hard
interactions in each event.
main12.cc
: a study of top events, fed in from the
Les Houches Event File ttbar.lhe
, here generated by
main53.f
. This file currently only contains 100 events
so as not to make the distributed PYTHIA package too big, and so serves
mainly as a demonstration of the principles involved.
main13.cc
: a more sophisticated variant of
main12.cc
, where two Les Houches Event Files
(ttbar.lhe
and ttbar2.lhe
) successively
are used as input. Also illustrating some other aspects, like the
capability to mix in internally generated events.
main14.cc
: a systematic comparison of several
cross section values with their corresponding values in PYTHIA 6.4,
the latter available as a table in the code.
main15.cc
: loop over several tries to do B decays
in an event, while keeping rest of event unchanged, as a way to
increase efficiency.
main16.cc
: put all user analysis code into a class
of its own, separate from the main program; provide the "cards file"
name as a command-line argument.
main17.cc
: collect the Pythia calls in a wrapper class,
thereby simplifying the main program; provide the "cards file" name
as a command-line argument.
main21.cc
: an example how parton-level configurations
can be input directly for hadronization, without being tied to the
full process-generation machinery, e.g. to study the hadronization of
junction topologies.
main22.cc
: tests of internally implemented cross sections
for Supersymmetric particle production, with SYSY spectrum defined in
main22.spc
and settings in main22.cmnd
.
main23.cc
: shows how an external decay handler can
be linked to handle the decays of some particles.
main24.cc
: shows how an external random number
generator can be linked to replace the internal one.
main25.cc
: shows how an external process can be
implemented as a new class derived from a PYTHIA base class, and then
handed in for generation as with a normal internal process.
main26.cc
: shows how an external resonance can be
implemented as a new class derived from a PYTHIA base class, and be
used in an external process, both of which are then handed in for
generation as with a normal internal resonance and process.
main31.cc
: similar to main01, except that the
event record is output in the HepMC event record format. Requires
that HepMC and CLHEP are properly linked.
main32.cc
: a streamlined version for the generation
of events that are then stored in HepMC format, without any event
analysis. That is, all physics studies will have to be done afterwards.
The name of the input "cards file" (e.g. main32.cmnd
)
and output HepMC event file are to be provided as command-line arguments.
Requires that HepMC and CLHEP are properly linked.
main41.cc
: a test of the shape of parton densities,
as a check prior to using a given PDF set in a generator. Requires
that LHAPDF is properly linked.
main42.cc
: compares the charged multiplicity
distribution, and a few other aspects, between default PYTHIA PDF and
another one. Requires that LHAPDF is properly linked.
main51.cc
: a simple example how the Les Houches
Accord interface, plus a few more Fortran-to-C++ commands, allows
hard processes to be generated by PYTHIA 6.4 and then processed
further by PYTHIA 8. Requires that PYTHIA 6.4 is properly linked.
main52.cc
: a fairly extensive study of
event properties, with hard processes generated by PYTHIA 6.4.
It reads in a main52.fcmnd
file with commands specfically
for the Fortran PYTHIA 6.4 program and another main52.ccmnd
file illustrating several of the settings listed on these pages.
Requires that PYTHIA 6.4 is properly linked.
main53.f
: a Fortran program (!) showing how
PYTHIA 6.4 can be used to generate a Les Houches Event File
ttbar.lhe
with top events (which is used as input by
main12.cc
). This program can easily be modified to
generate other files, bigger and/or for other processes.
Requires that PYTHIA 6.4 is properly linked.
main54.cc
: a final example where PYTHIA 6.4 is used
to generate hard processes, which are directly input to be generated
in full by the internal machinery, using the settings in
main54.cmnd
, and the output consists of a file with
HepMC event records for further analysis. Requires that PYTHIA 6.4,
HepMC and CLHEP are properly linked.
Spares
For currently unforeseen purposes, a few dummy settings are made
available here. The user can set the desired value in a "cards file"
and then use that value in the main program as desired.
flag
Main:spareFlag1
(default = off
)
flag
Main:spareFlag2
(default = off
)
flag
Main:spareFlag3
(default = off
)
mode
Main:spareMode1
(default = 0
)
mode
Main:spareMode2
(default = 0
)
mode
Main:spareMode3
(default = 0
)
parm
Main:spareParm1
(default = 0.
)
parm
Main:spareParm2
(default = 0.
)
parm
Main:spareParm3
(default = 0.
)
word
Main:spareWord1
(default = void
)
word
Main:spareWord2
(default = void
)
word
Main:spareWord3
(default = void
)