Sample Main Programs
- Simple starting examples
- Use of cmnd file and alternative plotting
- Input from Les Houches Event files, or ditto output
- Output to HepMC files
- Output to ROOT and/or Rivet
- Matching and Merging
- LHAPDF usage and other PDF tests
- Jet Finders
- Parallelization
- Alternative code or event structure
- Adding new capabilities, notably with user hooks
- Reweighting
- Utilities
- Python main programs
- QCD physics in e^+e^-
- QCD physics in pp
- QCD physics in DIS, gamma-p, gamma-gamma
- Heavy flavours and onium physics
- Standard Model
- Parton Showers
- Heavy Ions
- Hadronization variations
- Hadronic rescattering
- Cosmic rays
- BSM physics
- Where did they go?
Descriptions of available classes, methods and settings are all
very good and useful. Ultimately they are necessary for you to
be able to fine-tune your runs to the task at hand. To get going,
however, nothing helps like having explicit examples to study.
This is what is provided in the examples subdirectory,
along with instructions how they should be run.
Over the years, the number of examples has expanded beyond original
expectations, driven in part by the increasing number of physics
models, in part by user request. As the intended two-digit
name space mainNN.cc started to fill up, examples were
added wherever space was available, and eventually a three-digit
alternative became unavoidable. With PYTHIA 8.311 an attempt is made
to restore some order by regrouping and renaming the main programs
in three-digit format mainNNN.cc throughout.
There is no unique way to order programs, however, since each program
can represent many aspects. The
Examples by Keywords
page allows a program to be associated with several keywords.
Here, however, we have tried to provide one possible ordering.
In a first group of examples, the progression is from the very
simplest standalone codes, on to the use of Les Houches input
and HepMC output, to land at Matching and Merging examples.
This is an order that rapidly brings us to the center of much
(most?) current LHC usage, but undersells how much can be done
in PYTHIA standalone. In a second program group we therefore study
how to use some of the tools that come with the program, and how
to introduce various extensions. A third and final group is structured
by physics topics.
In the new rearranged version, the numbering starts with
main101.cc. This largely but not completely avoids
clashes with the old numbering, i.e. that people erroneously would
assume that a former mainNN.cc is now to be found at
main0NN.cc. Instead we open up for main0NN.cc
being used in examples you write yourself for your private use.
Most of the new programs agree with former ones, only renamed,
and therefore we indicate by "(was mainNN.cc)"
the name used up until and including 8.311. Some minor modifications
may have been done, e.g. with pyplot output allowed as an option.
Furthermore, some new programs have been added, indicated by "(new)".
The main programs are arranged in ascending order of the new number.
The final subsection gives compact translation tables in the other
direction, from old to new numbers, in case you rapidly want to find
where your favourite example was moved.
Simple starting examples
These examples are of minimal size, to illustrate how to get going.
The formatting is uniquely dense, since a secondary application is
to be able to show all the code on a single slide in a presentation.
main101.cc (was main01.cc) :
a simple study of the charged multiplicity for jet events at the
LHC.main102.cc (was main02.cc) :
a simple study of the pT spectrum of Z bosons at the
Tevatron.main103.cc (new) :
basic generation of e^+e^- events at LEP 1.
Use of cmnd file and alternative plotting
While the generation process can be specified entirely in the main
program, it is useful to break out all settings and particle data
modifications in a separate command file that is read in from the
main program. The command file can then be modified, and the main
program rerun, without any need to recompile.
PYTHIA comes with its own simple histogramming package, to allow
analysis results to be presented with minimal effort. It is inspired
by HBOOK, the ancestor of the current ROOT package. The simple
line-printer output tends to confuse younger users, however, so an
alternative has been introduced. In it, Python Matplotlib/Pyplot code
can be generated with minimal fuss, a code that then can be run to
produce plots in a more familiar format. Furthermore PYTHIA comes
with a simplistic interface to the YODA histogramming package.
main111.cc (new) :
basic generation of e^+e^- events at LEP 1, equivalent with
main103.cmnd, but with settings delegated to the auxiliary
main111.cmnd file.main112.cc (new) :
a simple study of the pT spectrum of Z bosons at the Tevatron,
with Pyplot option for displaying the result, but otherwise equivalent
with main102.cc.main113.cc (was main03.cc) :
a simple study of several different kinds of events, with the choice
to be made in the main113.cmnd "cards file". Also shows
how to plot histograms using the Pyplot approach.main114.cc (new) :
demonstration of the simple interface to YODA
histogramming.
Input from Les Houches Event files, or ditto output
While PYTHIA comes with an extensive library of matrix elements,
it is by far not enough to cover all applications of interest.
It is therefore necessary to provide a way to feed in the core
hard process of events from external generators, and then let
PYTHIA take it from there. The standard format for such an
information transfer is the Les Houches Event File.
main121.cc (was main11.cc) :
a study of top events, fed in from the Les Houches Event File
ttbar.lhe, here generated by PYTHIA 6.4. 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.main122.cc (was main12.cc) :
a more sophisticated variant of main121.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.main123.cc (was main13.cc) :
a streamlined version of main122.cc, where two Les Houches
Event Files (ttbar.lhe and ttbar2.lhe)
successively are used as input in main123.cmnd file.main124.cc (was main20.cc) :
shows how PYTHIA 8 can write a Les Houches Event File, using facilities
potentially useful also for other programs to write an LHEF. See also
main125.cc.main125.cc (was main64.cc) :
exemplifies how LHEF version 3 events can be written on an external
file.main126.cc (was main37.cc) :
shows how LHEF version 3.0 files can be read and used to fill several
histograms of the same property, but with different event weights.main127.cc (was main38.cc) :
an extended version of main126.cc, where additionally
it is shown how to extract many different kinds of LHEF version 3.0
information.
Output to HepMC files
Generated PYTHIA events can be analyzed directly in the main program,
but often they need to be processed further outside of PYTHIA, e.g.
to simulate the detector response. The HepMC package provides a
standardized format for this transfer of such information.
main131.cc (was main41.cc) :
similar to main101, except that the event record is output
in the HepMC event record format. Requires that HepMC3 is properly
linked. Note that the main131.hepmc output file can become
quite big; so no example is included in this distribution.main132.cc (was main42.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. main132.cmnd) and output HepMC event file
(e.g. main132.hepmc) are to be provided as command-line
arguments. Requires that HepMC3 is properly linked. Note that the
HepMC output file can become quite big; so no example is included in
this distribution.main133.cc (was main43.cc) :
a further extension of main132.cc, where subruns are used
to process several consecutive LHEF, as in main123.cc,
with information stored e.g in main133.cmnd. Other
comments as for main132.cc.main134.cc (was main44.cc and
main45.cc) :
a legacy HepMC2 example, alternatively HepMC3, where subruns are
used to process several consecutive LHEF, with information stored
e.g in main134.cmnd.main135.cc (new) :
illustrates how the event record can be compressed to include e.g.
only the final-state particles, in order to reduce the HepMC file size,
but obviously at the expense of losing some history information.main136.cc (was main46.cc) :
an example illustrating the generation of HepMC events using the
HDF5 LHA format (LHAHDF5).
Output to ROOT and/or Rivet
Another package commonly used for data storage and histogramming
is ROOT, and again it is possible to transfer information as needed.
The Rivet package emulates a number of old experimental analyses,
and thereby allows a comparison between generators and data under
controlled conditions.
main141.cc (was main94.cc) :
use ROOT to visualize the particles produced by Pythia in
(y,phi) space.main142.cc (was main95.cc) :
use ROOT to visualize different jet algoritms in (y,phi) space.
The jet clustering is done with FastJet. The produced figure was
used in the article "50 years of Quantum Chromodynamics" in
celebration of the 50th anniversary of QCD (EPJC).main143.cc (was main91.cc) :
shows how ROOT can be used for histogramming in a program that for
the rest is structured like a normal PYTHIA run.main144.cc (was main93.cc) :
streamlined event generation with possibility to output ROOT files,
output HepMC files and run RIVET analyses, all by specifying output
modes in a cmnd file, where also the event generator settings are
specified. The example is run with command line options, run
./main144 -h to see a full list. See
ROOT Usage for information
about ROOT output, RIVET Usage for
information about RIVET and HepMC
Interface for information about HepMC.
Matching and Merging
One of the most important particle physics advances in recent years
is the capability to do calculations both for multi-body final states,
and to higher orders. Such calculations need to be combined with each
other and with parton showers in a way to avoid both doublecounting
and gaps in the coverage of phase space. There is not one unique
method that is demonstably the best, but rather it depends on the
conditions. Methods intended to provide a smooth transition from the
matrix-element to the parton-shower picture are called matching,
while those intended to combine different jet multiplicities are
called merging. Usually the two aspects are be combined to produce
an overall picture, and the dividing line may then be unclear.
main151.cc (new) :
demonstrates MC@NLO matching with LHEF input from MadGraph5_aMC@NLO.
Input is provided by the main151.cmnd file.main152.cc (was main31.cc) :
exemplifies an improved matching of parton showers to LHEF-style input
based on the POWHEG approach. The
main152.cmnd allows to switch between several different
matching options. It also allows to select input process, in this case
either for the POWHEG-hvq program applied to top pair production
[Cor10] or for QCD 2+3-jet events. The small samples of input
events are stored in the powheg-hvq.lhe and
powheg-dijets.lhe files, respectively.main153.cc (was main34.cc) :
demonstrates how Madgraph5_aMC@NLO can be run "from within" Pythia,
making use of the LHAupMadgraph wrapper/interface of
Madgraph5_aMC@NLO and the Pythia jet matching facilities.main154.cc (was main33.cc) :
demonstrates how to link the POWHEGBOX matrix element programs dynamically,
bypassing the need for intermediate LHE files. Two special files are used
in this option: include/Pythia8Plugins/LHAPowheg.h contains
the LHAup class wrapper used to build the POWHEG plugin libraries, and
include/Pythia8Plugins/PowhegProcs.h the simple class
that facilitates loading the POWHEG plugins. In addition
main154.cmnd contains the commands needed for POWHEGBOX to
run the example.main161.cc (was main82.cc) :
exemplifies CKKW-L merging with a user-defined merging scale.
Input is provided by the main161.cmnd file.main162.cc
(combination of main80/85/86/87/88/280.cc) :
exemplifies various multi-jet merging schemes in Pythia, depending
on the .cmnd input file:
main162ckkwl.cmnd for CKKW-L,
main162umeps.cmnd for UMEPS,
main162nl3.cmnd for NL3,
main162unlops.cmnd for UNLOPS,
main162mess.cmnd for Vincia's CKKW-L sector merging (MESS).main163.cc (was main32.cc) :
exemplifies MLM merging, either in the ALPGEN variant or in the Madgraph
one, and with input events either from ALPGEN or from Madgraph, with
relevant control cards stored in main163.cmnd. See
Jet Matching for further details.
Traditionally the ALPGEN output is split into one file with events and
another with parameters and cross sections (unlike in LHEF). Here a
sample of W + 3 jets events is stored in main163.unw
and the parameters to go with it in main163_unw.par.
Madgraph events are taken from the w+_production_lhc_2.lhe
file in this case.main164.cc (extension of main89.cc) :
general main program to use Pythia's matching and merging schemes.
Which method is used is specified by the .cmnd input file:
main164mcatnlo.cmnd for MC@NLO matching with Madgraph5_aMC@NLO,
main164powheg.cmnd for POWHEG matching with POWHEG-BOX,
main164ckkwl.cmnd for CKKW-L merging,
main164mess.cmnd for Vincia's CKKW-L sector merging (MESS),
main164umeps.cmnd for UMEPS merging,
main164unlops.cmnd for UNLOPS merging,
main164mlm.cmnd for MLM jet matching,
main164fxfx.cmnd for FxFx merging.
LHAPDF usage and other PDF tests
PYTHIA comes with a set of parton distribution functions (PDFs),
some older for legacy comparisons and some more recent ones.
It is also possible to read in and ise a new PDF set stored in the
lhagrid1 data format, which is the current standard.
This is sufficient for many applications, but there are others
where a broader range of options need to be tried, e.g. to provide
PDF error bands. This can be achieved by linking to the LHAPDF library.
main201.cc (was main51.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.
Also shows how to plot histograms (with logarithmic x scale)
using the Pyplot solution.main202.cc (was main52.cc) :
compares the charged multiplicity distribution, and a few other
minimum-bias physics aspects, between default PYTHIA PDF and another
one. Requires that LHAPDF is properly linked.main203.cc (was main54.cc) :
compares the internal and LHAPDF implementations of the NNPDF 2.3
QCD+QED sets, for results and for timing. Requires that LHAPDF is
properly linked.main204.cc (was main53.cc) :
tests the possibility to do backwards evolution from an incoming
photon at the hard interaction. Input in main204.cmnd and
photoninproton.lhe. Requires that you link to a LHAPDF set
that includes the photon PDF.
Jet Finders
The reconstruction of jets in events has a long history, but for LHC
applications the related kT, anti-kT and Cambridge/Aachen (no-kT)
algorithms have set the standard. These are available, in three
different ways. Firstly, as completely internal implementations.
Secondly by using the faster fjCore code, included in the
PYTHIA distribution by gracious permission from FastJet
authors. Both of these are available via the SlowJet
frontend, and allow standardized information transfer. Thirdly, it is
possible to link to the full FastJet pckage, to access
also a growing number of add-ons to the basic algorithms.
Also some older jet finders are available, like the Durham one common
for e^+e^- events, along with other event measures like Thrust.
main211.cc (was main05.cc) :
generation of QCD jet events at the LHC, with jet analysis using the
SlowJet inclusive anti-kT sequential-recombination
finder.main212.cc (was main71.cc) :
an example how the FastJet jet finding package can be
linked to allow an analysis of the final state, in this case for a study
of W + jet production.main213.cc (was main72.cc) :
a comparison of SlowJet and FastJet jet finding,
showing that they find the same jets if run under identical conditions,
in this case for QCD jets.main214.cc (was main73.cc) :
a comparison of jet properties on the parton and the hadron level,
illustrating possibilities for larger control of which particles are
used in the jet analyses.main215.cc (was main74.cc) :
exemplifies how to use one of the contributed add-ons to the
FastJet package. In this case the modified Mass Drop Tagger
is used to improve the mass reconstruction of a boosted hadronically
decaying Z^0.main216.cc (new) :
reconstruction of a hypothetical 1 TeV Z' mass by forming the
invariant mass of the two jets with highest transverse momentum.
Convenient starting point for student exercises.
Parallelization
The simplest way of parallelization is to run several PYTHIA instances,
basically as many as there are cores available. Assuming you remember
to set a separate random-number seed, you can run otherwise identical
main programs to generate more events in a given time. This is the
normal flow in an experiment, where the combination of the different
generated event samples occurs later, typically only after detector
simulation. For standalone studies it may be annoying to have to
manage several runs, and write extra code for combining the statistics
afterwards, however. This groups of programs illustrates simpler ways
to run several PYTHIA instances in parallel, but with statistics
accumulated in one place.
main221.cc (was main161.cc) :
gives an example of PythiaParallelism usage. This program
is equivalent to main101.cc, but does event generation
in parallel.main222.cc (was main162.cc) :
equivalent to main221.cc, but is much more heavily commented
to give more in-depth explanations of how the code works.main223.cc (was main163.cc) :
perform analyses in parallel using the
Parallelism:processAsync setting.main224.cc (was main300.cc) :
allows to steer Pythia from the command line, can produce HepMC files,
and allows for OpenMP parallelization. More documentation can be
obtained by executing ./main224 --help. The input file
main224.cmnd further illustrates the use of DIRE.
Alternative code or event structure
Most examples follow a common main-program structure: setup - loop with
generation and study of the generated events - final output. This
section exemplifies that this basic pattern can be modified in various
ways.
main231.cc (was main16.cc) :
put all user analysis code into a class of its own, separate from the main
program, and provide the "cards file" name as a command-line argument.
Also exemplifies how Higgs mass, width and branching ratios can be set
by hand.main232.cc (was main18.cc) :
shows how to write an event filter class, where you keep a vector of
pointers to the subset of particles you want to study further. The event
record itself remains unchanged.main233.cc (was main30.cc) :
example how to create a tailor-made copy of the ordinary event record,
here with hard-process history tracing closer to the PYTHIA 6
conventions.main234.cc (was main21.cc) :
an example how a single particle or various 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. Can also be used for single-resonance decays,
with showers.
Adding new capabilities, notably with user hooks
There are various way in which external code can be directly linked into
the generation process. This goes for hard matrix elements, parton
distributions, new particles, alternative random number generators,
and more. The UserHooks class allows a more fine-grained
control, where new code can be inserted at specified locations e.g inside
parton showers or hadronization routines. Some of these possibilities
are explored here.
main241.cc (was main07.cc) :
set up a fictitious production process to a generic resonance, where you
easily can compose your own list of (two-body) decay modes to a variety of
final states. Also traces decay chains down to truly stable particles:
gamma, e^+-, p/pbar and neutrinos. Suitable
for astroparticle applications, like neutralino pair annihilation, where
cross sections are calculated separately in another program. Also shows
how to plot histograms using the Pyplot solution.main242.cc (was main10.cc) :
illustration how UserHooks can be used interact directly
with the event-generation process.main243.cc (was main17.cc) :
shows (a) how to use UserHooks to regularize onium cross
section for pT → 0, and (b) how decays could be handled
externally.main244.cc (was main22.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
them handed in for generation as with normal internal classes.main245.cc (was main23.cc) :
shows how to write external classes, derived from PYTHIA base classes,
that can be handed to PYTHIA for internal generation.
The MIXMAX random number generator is this way compared
with the default PYTHIA one. Explicit implementations are included for
the generation of external beam momentum spread and vertex location,
and for a simple scaling external parton distribution set.main246.cc (was main62.cc) :
illustrates how a user hook can be made to steer the angular distribution
selection in resonance decays. The prime example would be if LHEF input,
e.g. from Madgraph, contains undecayed resonances with helicity information.
These would then be decayed isotropically by PYTHIA, but this example
shows how one could do better. Some input in
main246.cmnd.main247.cc (was main333.cc) :
illustrates the use of UserHooks to veto events after
hadronization, but before any subsequent processes such as rescattering or
Bose-Einstein.main248.cc (was main103.cc) :
shows how to use a filter to select a specific final state from resonance
decays.
Reweighting
An application that is receiving increased attention is to provide error
bands in distributions, not by several runs with different parameter
values, but by one run where events receive multiple weights, each
corresponding to the impact of a variation.
main261.cc (was main63.cc) :
exemplifies how rare emissions can be enhanced in the shower.main262.cc (was main121.cc) :
set up automatic uncertainty band variations to PDFs and factorization
and renormalization scales.main263.cc (was main301.cc) :
demonstrates the use of in-situ hadronization reweighting for
variations of both kinematic and flavor hadronization parameters.
The output compares multiplicity distributions from the default
parameters to the reweighted output with the varied parameters
and the output using the varied parameters without reweighting.main264.cc (name) :
runs the same analysis as main264.cc but only for flavor
hadronization parameters and demonstrates post-hoc reweighting rathern
than in-situ.
Utilities
Some odds and ends.
main281.cc (new) :
shows different ways to print out and read back in settings and particle
data. Useful notably for permanent updates of the latter.main282.cc (was 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.
Python main programs
Core PYTHIA is entirely written in C++, but it can also be called from
other languages. Notably we provide an interface to Python. Here are a
few examples how this can be used, with Python code equivalent to some
of the C++ main programs.
main291.py (was main01.py) :
a Python interface equivalent to main101.cc, i.e. a minimal
example.main292.py (was main10.py) :
a Python interface equivalent to main222.cc. Provides an
example of how to derive PYTHIA classes in Python.main293.py :
a Python interface equivalent to main242.cc. Demonstrates
usage of a PYTHIA plugin within the Python interface.main294.py (was main39.py) :
standalone Python code that parses the XML particle database and displays
data for a requested particle.main295.py (was main34.py) :
a Python interface equivalent to main154.cc,
with interface to Madgraph.main296.cc (new) :
illustrates how a user can compile a simple Pythia wrapper class
written in C++ (studying total cross sections) as a shared
library.main296.py (new) :
Python script studying total cross sections that accesses Pythia via
the simple C++ Pythia wrapper class main296Lib.cc. This
wrapper module must be compiled with make
libmain296Lib.so.main297.py (new) :
generates batches of events via an interface with Awkward array.main298.py (new) :
further examples on how to work with events via the Awkward array
interface.
QCD physics in e^+e^-
With LHC physics so dominant, e^+e^- collisions may easily be
forgotten. But they are fully supported, and used e.g. in FCC-ee studies.
If they are given less attention, it is rather that it is so much easier
to set up such runs, since there is no need to model MPIs, beam remnants
and more. Some examples have already been given, starting with
main103.cc, but here comes some more.
main301.cc (was main06.cc) :
generation of LEP1 hadronic events, i.e.
e^+e^- → gamma*/Z^0 → q qbar, with charged
multiplicity, sphericity, thrust and jet analysis.main302.cc (new) :
colour reconnection rate in
e^+e^- → W^+W^- → q_1 qbar_2 q_3 qbar_4
as a function of the collision energy.
QCD physics in pp
The field of pp physics is rich, and the many main programs already
presented only scratch the surface. Here comes some more examples.
main321.cc (was main06.cc) :
tests of cross sections, multiplicities and average transverse momenta
for elastic, diffractive and nondiffractive topologies, using
main321.cmnd to pick processes. For photoproduction one
can use the alternative main321photons.cmnd input.main322.cc (was main08.cc) :
generation of the QCD jet cross section biased towards higher pT
values, by two different techniques. Firstly, by splitting the run into
subruns, each in its own pT bin, and adding the results properly
reweighted. Two suboptions, with limits set either in the main program or
by subrun specification in the main322.cmnd file. Secondly,
by a continuous reweighting with a pT^4 bias in the selection,
compensated by a 1/pT^4 event weight. Also inclusion of soft
processes is illustrated, with subruns and weighted events.main323.cc (was main09.cc) :
generation of two predetermined hard interactions in each event.main324.cc (was main19.cc) :
use several instances of Pythia, one for signal events and others for
a variable number of pileup and "beam-gas" events, combined into one
common event record. Illustrates how new Pythia instances can copy
existing settings and particle data.main325.cc (was main61.cc) :
exemplifies the generation of hard diffractive processes.main326.cc (was main77.cc) :
example on how double parton scattering events can be reweighted
according to a different model than default in Pythia. Contributed by
Boris Blok and Paolo Gunnellini.main327.cc (new) :
study forward proton production in a 7 TeV sample of inelastic events,
both diffractive and nondiffractive. Compare default, ditto without
popcorn for remnant diquark, and the QCDCR model.main328.cc (new) :
study total, elastic and diffractive cross sections in several models
(SaS/DL; MBR, ABMST, RPP2016) as a function of collision energy.main329.cc (new) :
comparison of charged multiplicity distributions with data at 200 (UA5),
900 (UA5) and 1800 (E735) GeV.
QCD physics in DIS, gamma-p, gamma-gamma
Physics involving photons can come in several shapes. Here we gather
some examples where real or virtual photons take part in the hard
interactions. One of the limitations of PYTHIA is that there is not
yet a description of the transition from real to virtual, so the two
cases have to be considered separately. Photon emission as part of the
initial- or final-state parton showers are modelled by default, but are
not studied specifically here.
main341.cc (was main36.cc) :
demonstrates how to generate Deeply Inelastic Scattering events,
e.g. in a HERA configuration.main342.cc (was main68.cc) :
exemplifies hard diffraction in the context of a photon-inside-lepton
beam, like at HERA.main343.cc (was main69.cc) :
exemplifies how to generate all relevant contributions for charged
particle spectra in photon-photon and photon-proton collisions.main344.cc (was main70.cc) :
exemplifies how to provide an external photon flux for photo-production
processes.main345.cc (was main78.cc) :
demonstrates how to generate different types of photon-initiated
dilepton events in proton-proton collisions.
Heavy flavours and onium physics
With heavy flavours we here mean charm, bottom and top quarks.
The latter are too short-lived to form hadrons, and also way more
massive, so the descriptions of charm and bottom on one side and
top on the other are quite separate. Of special interest is the
formation of charmonium and bottomonium states, which offer
interesting probes of the hadronization process.
main361.cc (was main15.cc) :
loop over several tries, either to redo B decays only or to redo
the complete hadronization chain of an event. This is a way to increase
efficiency, since much of the generation process is only made once.main362.cc (was main29.cc) :
colour reconnection models studied for top production. Illustrates
how to set up the user hooks in
include/Pythia8Plugins/ColourReconnectionHooks.h, with
several models not found in the standard PYTHIA library.main363.cc (was main35.cc) :
demonstrates how to generate quarkonia events with the external
HelacOnia package interfaced to Pythia, and compare results
with the internal implementation.main364.cc (was main48.cc) :
demonstrates how to use the EvtGenDecays class provided by
include/Pythia8Plugins/EvtGen.h to perform decays with
the EvtGen package. The main364.dec header
contains special instructions how to configure PYTHIA for use with
EvtGen.main365.cc (was main40.cc) :
calculates the inclusive branching fractions for the Standard Model
Higgs into quarkonia using the LETO timelike parton shower.main366.cc (new) :
calculates charm hadron asymmetries in fixed-target pi^- p
collisions, and compares results with data at three reasonably nearby
energies.A few options are available, e.g. the QCDCR model.main367.cc (new) :
presents a fictitious scenario where the top is long-lived enough to
hadronize. This is studied using the R-hadron machinery, in
e^+e^- or pp collisions.
Standard Model
The Standard-Model selection, excluding the QCD and photon sectors
already covered above, would include notably the production of
Z^0 and W^+-. These are among the simplest processes
to exemplify a number of coding aspects with, however, so have already
been well illustrated, starting with main102.cc. For now
we therefore only provide an example with the final Standard Model
particle, the Higgs.
main381.cc (new) : Higgs production in an 500 GeV
e^+e^- coillider, illustrating the composition of production
channels and the charged multiplicity arising in each of them.
Parton Showers
Parton showers are everywhere, and are taken for granted in the
examples above. But note that PYTHIA contains three different
showers, the default simple one, VINCIA and DIRE. The latter
two aim for higher theoretical accuracy, but have not yet been
equipped to handle as many different cases with as many variations.
In this section the aim is mainly to highlight VINCIA, and to some
extent also DIRE.
main401.cc (was main200.cc) :
simple example of the VINCIA (or DIRE) shower model(s), on Z decays
at LEP I, with some basic event shapes, spectra, and multiplicity
counts.main402.cc (was main201.cc) :
comparison of VINCIA and Pythia on
inclusive jets at LHC, with option to run the two generators in
parallel using OpenMP. See main204.cc for how to do this
with the Parallelism framework.main403.cc (was main202.cc) :
VINCIA setup for ttbar production at
LHC, with measurement of run time and options to switch various shower
and MPI/hadronization components on/off via command file.main404.cc (was main204.cc) :
demonstrates the example of
main201 using the Parallelism framework.main405.cc (was main205.cc) :
VINCIA setup for electroweak shower off
a fictitious process for Z decay to neutrinos at high
mass. (In the absence of a weak shower, these would not shower at
all.) The VINCIA EW shower requires hard-process partons with
assigned helicities. This is done via Pythia's MG5 matrix-element
interface, which must be compiled and linked (using configure
--with-mg5mes).main406.cc (was main206.cc) :
previously main203.cc
VINCIA setup for electroweak shower off high-pT dijets at the LHC. The
VINCIA EW shower requires hard-process partons with assigned
helicities. This is done via Pythia's MG5 matrix-element interface,
which must be compiled and linked (using configure
--with-mg5mes).main407.cc (was main207.cc) :
VINCIA electroweak showers off an LHEF
file for dark-matter annihilation. The VINCIA EW shower requires
hard-process partons with assigned helicities. In this example, these
are read in from the LHEF file.main408.cc (was main208.cc) :
VINCIA setup for double-dissociative
photon-initiated gamma gamma → mu+ mu- at LHC.
Heavy Ions
The Angantyr model is part of an effort to apply the strengths of PYTHIA
to heavy-ion collisions, by judicious extensions. For comparisons
with data it is necessary to subdivide events into centrality bins,
which necessitates a two-step process in the main program.
main421.cc (was main111.cc) :
simple pp collisions as in main101.cc, but using the
Angantyr model for Heavy Ion collisions. Also shows how Rivet analyses
can be set up easily using a special interface.main422.cc (was main112.cc) :
p-Pb collisions at LHC energies, using the Angantyr model for
Heavy Ion collisions, and analyzing events by centrality bins.main423.cc (was main113.cc) :
Pb-Pb collisions at LHC energies, using the Angantyr model for Heavy Ion
collisions, and analyzing events by centrality bins.main424.cc (new) : variable beam energy and types for
hadron-ion collisions, where the initialization can be cached for
later use.main425.cc (new) : calculates the proton-oxygen
cross section at varying energies.main426.cc (new) : exemplifies adding new nuclei and
extracting various cross sections and Glauber statistics from Angantyr.main427.cc (new) : add a different impact parameter
sampler to Angantyr, to output events with unit weights.
Hadronization variations
The Lund string model has been successful in many respects, but also
shown to have limitations. Therefore it is always of interest to try to
extend or modify it in different directions.
main441.cc (was main101.cc) :
shows how the string shoving mechanism, part of the rope hadronization
framework, can be set up and used to generate ridge effects.main442.cc (was main102.cc) :
shows how flavour production is changed in the rope hadronization
framework.main443.cc (new) : study particle composition in the
thermal/exponential model for flavour production, compared with the
standard tunneling/Gaussian ansatz.
Hadronic rescattering
In hadronic collisions, and even more so in heavy-ion ones, a major
fraction of the hadrons are produced so close to other hadrons that
wave functions overlap. It is therefore to be expected that hadrons
can rescatter, and change both flavours and momenta. Fortunately
particles produced nearby in space-time also tend to have similar
velocity vectors, resulting in fairly soft interactions, or else
effdects would have been more dramatic than they are. Even so,
collective flow and other observables can be significantly affected
by it. The examples below illustrate both the rescattering model as
part of the event-generation chain and the underlying modelling itself.
main461.cc (was main151.cc) :
compare the energy dependence of the average charged multiplicity
between the simple treatment in rescattering and the full framework.main462.cc (was main152.cc) :
compare multiplicities and pT spectra with or without rescattering,
the former with or without rescattering between nearest neighbours along
the string.main463.cc (was main153.cc) :
simple generation of low-energy events.main464.cc (was main154.cc) :
plot the energy dependence of the low-energy cross sections used in the
hadronic rescattering framework.main465.cc (was main155.cc) :
plot the energy dependence of the low-energy cross sections, specifically
the contribution from resonances.main466.cc (was main156.cc) :
perform parameterization of hadron widths and output the resulting
tables.main467.cc (was main157.cc) :
generate tetraquarks from the rescattering of a D0 and
Dbar*0 beam.main468.cc (was main158.cc) :
generate tetraquarks from the rescattering of D0 and
Dbar*0 mesons produced in LHC events.main469.cc (new) :
show as a function of time and distance, from 1 fm to 1 m, how particles
are produced, decay and rescatter.
Cosmic rays
With the hadronic rescattering code added to PYTHIA, it becomes possible
to simulate hadronic collisions from a few hundred MeV kinetic energy
up to around 100 TeV, or even above that. This effectively covers
the range of energies in cosmic ray cascades in the atmosphere,
and so PYTHIA now can simulate the hadronic part of such cascades.
For this task, it is also necessary to allow other particles than only
protons and neutrons to cascade, to include nuclear targets in the
atmosphere, and to switch rapidly between such different particles at
different energies as the cascade evolves. The code could also be used
for cascades in a solid detector material. This framework is new,
and comparisons with data are still scarce.
main481.cc (was main181.cc) :
plot PDFs for a large number of hadrons.main482.cc (was main182.cc) :
test switching between hadron beams on an event-by-event basis. Compare
running times for different scenarios.main483.cc (was main183.cc) :
simple example of how Pythia can be used to simulate a basic hadronic
cascade in a few simple atmospheres, either as a sequence of hadron-hadron
collisions or making use of the Angantyr module.main484.cc (was main184.cc) :
as main483.cc, but using the PythiaCascade class
to perform the separate collisions or decays, while the bookkeeping
of the cascade evolution remains in the main program.main485.cc (was main185.cc) :
an even simpler example of one collision or decay at a time, as performed
in PythiaCascade.main486.cc (new) :
study total and inelastic cross section for various beam combinations,
using the public methods in the Pythia class. These
methods are intended for fast switching, and only provide the SaS/DL
ansats at high energies.main487.cc (new) :
direct comparison of a hadronic cascade simulated either with
PythiaCascade or with Angantyr. Here the
atmosphere is a realistic mix of nitrogen, oxygen and argon.
BSM physics
The search for physics Beyond the Standard Model may well constitute
the majority of all experimental particle physics articles published.
It is therefore natural that PYTHIA is designed to handle a plethora
of such scenarios, in part by internal code, in part by external
hard-process input. In some cases, like Baryon-Number Violation or
Hidden-Valley phenomena, this extends on our modelling of normal QCD
phenomena. Below some examples from the wide field of possibilities.
main501.cc (was main24.cc) :
tests of internally implemented cross sections for Supersymmetric
particle production, with SUSY spectrum defined in
slha2-example.spc and settings in
main501.cmnd. For illustration, an alternative example
spectrum is also available, sps1aWithDecays.spc, which
contains a decay table in SLHA format.main502.cc (was main25.cc) :
input RPV-SUSY events from an LHEF file that contains an SLHA spectrum
inside its header. The event file, main502.lhe, contains
a sample events that illustrate how to arrange color tags in the
presence of the color-space epsilon tensors that accompany baryon
number violating event topologies.main503.cc (was main26.cc) :
test program for processes in scenarios with large extra dimensions
or unparticles.main504.cc (was main27.cc) :
production of Kaluza-Klein gamma/Z states in TeV-sized
extra dimensions.main505.cc (was main28.cc) :
production of long-lived R-hadrons, that are forced to decay at
separate vertices and possibly with changed momenta.main506.cc (was main55.cc) :
exemplifies how you can use the internal implementation of
interpolation in an lhagrid1.dat file, without linking
LHAPDF6. Also illustrates the topical issue of associated event
properties for an intermediate spinless resonance in
γ + γ → γ + γ at 750 GeV.main507.cc (was main75.cc) :
setup (in main507.cmnd) for Dark Matter production via
an s-channel mediator, where a mono-jet pT spectrum
is found with the FastJet package.main508.cc (was main76.cc) :
simple setup for Dark Matter production in several different scenarios,
as specified in main508.cmnd, notably with long-lived
particle signatures.main509.cc (was main171.cc) :
three scenarios for Hidden Valley particle production at 13 TeV,
with a selection of further possible variations.main510.cc (new) :
a related setup of a few different scenarios for Hidden Valley
particle production at a 1 TeV e^+e^- collider.main511.cc (new) :
demonstrates consistency of the Hidden Valley fragmentation framework,
by comparing a scaled-up HV version of two-flavour (u/d) QCD
with its QCD original, for three different ways to set HV fragmentation
parameters.
Where did they go?
Here you can find how the former main programs were renumbered,
and in several cases also upgraded, so the correspondence is not
always perfect.
Tables for the translation from the old C++ names to the new ones:
| old | new | comment |
|---|
| main01 | main101 | |
| main02 | main102 | + main112 |
| main03 | main113 | |
| main04 | main321 | |
| main05 | main211 | |
| main06 | main301 | |
| main07 | main241 | |
| main08 | main322 | |
| main09 | main323 | |
| main10 | main242 | |
| main11 | main121 | |
| main12 | main122 | |
| main13 | main123 | |
| main14 | main282 | |
| main15 | main361 | |
| main16 | main231 | |
| main17 | main243 | |
| main18 | main232 | |
| main19 | main324 | |
| main20 | main124 | |
| main21 | main234 | |
| main22 | main244 | |
| main23 | main245 | |
| main24 | main501 | |
| main25 | main502 | |
| main26 | main503 | |
| main27 | main504 | |
| main28 | main505 | |
| main29 | main362 | |
| main30 | main233 | |
| main31 | main152 | |
| main32 | main163 | |
| main33 | main154 | |
| main34 | main153 | |
| main35 | main363 | |
| main36 | main341 | |
| main37 | main126 | |
| main38 | main127 | |
| main40 | main365 | |
| old | new | comment |
|---|
| main41 | main131 | |
| main42 | main132 | |
| main43 | main133 | |
| main44 | main134 | joined |
| main45 | main134 | joined |
| main46 | main136 | |
| main48 | main364 | |
| main51 | main201 | |
| main52 | main202 | |
| main53 | main204 | |
| main54 | main203 | |
| main55 | main506 | |
| main61 | main325 | |
| main62 | main246 | |
| main63 | main261 | |
| main64 | main125 | |
| main68 | main342 | |
| main69 | main343 | |
| main70 | main344 | |
| main71 | main212 | |
| main72 | main213 | |
| main73 | main214 | |
| main74 | main215 | |
| main75 | main507 | |
| main76 | main508 | |
| main77 | main326 | |
| main78 | main345 | |
| main80 | main162 | joined |
| main81 | | removed |
| main82 | main161 | |
| main83 | | removed |
| main84 | | removed |
| main85 | main162 | joined |
| main86 | main162 | joined |
| main87 | main162 | joined |
| main88 | main162 | joined |
| main89 | main164 | |
| main91 | main143 | |
| main92 | | removed |
| old | new | comment |
|---|
| main93 | main144 | |
| main94 | main141 | |
| main95 | main142 | |
| main101 | main441 | |
| main102 | main442 | |
| main103 | main248 | |
| main111 | main421 | |
| main112 | main422 | |
| main113 | main423 | |
| main121 | main262 | |
| main151 | main461 | |
| main152 | main462 | |
| main153 | main463 | |
| main154 | main464 | |
| main155 | main465 | |
| main156 | main466 | |
| main157 | main467 | |
| main158 | main468 | |
| main161 | main221 | |
| main162 | main222 | |
| main163 | main223 | |
| main171 | main509 | |
| main181 | main481 | |
| main182 | main482 | |
| main183 | main483 | |
| main184 | main484 | |
| main185 | main485 | |
| main200 | main401 | |
| main201 | main402 | |
| main202 | main403 | |
| main204 | main404 | |
| main205 | main405 | |
| main206 | main406 | |
| main207 | main407 | |
| main208 | main408 | |
| main280 | main162 | joined |
| main300 | main224 | |
| main301 | main263 | |
| main333 | main247 | |
Table for the translation from the old Python names to the new ones:
| old | new |
|---|
| main01.py | main291.py |
| main10.py | main293.py |
| main34.py | main295.py |
| main39.py | main294.py |
| main162.py | main292.py |