Sample Main Programs

  1. Simple starting examples
  2. Use of cmnd file and/or Pyplot
  3. Input from Les Houches Event files, or ditto output
  4. Output to HepMC files
  5. Output to ROOT and/or Rivet
  6. Matching and Merging
  7. LHAPDF usage and other PDF tests
  8. Jet Finders
  9. Parallelization
  10. Alternative code or event structure
  11. Adding new capabilities, notably with user hooks
  12. Reweighting
  13. Utilities
  14. Python main programs
  15. QCD physics in e^+e^-
  16. QCD physics in pp
  17. QCD physics in DIS, gamma-p, gamma-gamma
  18. Heavy flavours and onium physics
  19. Standard Model
  20. Parton Showers
  21. Heavy Ions
  22. Hadronization variations
  23. Hadronic rescattering
  24. Cosmic rays
  25. BSM physics
  26. 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.

Use of cmnd file and/or Pyplot

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Utilities

Some odds and ends.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

oldnewcomment
main01main101
main02main102+ main112
main03main113
main04main321
main05main211
main06main301
main07main241
main08main322
main09main323
main10main242
main11main121
main12main122
main13main123
main14main282
main15main361
main16main231
main17main243
main18main232
main19main324
main20main124
main21main234
main22main244
main23main245
main24main501
main25main502
main26main503
main27main504
main28main505
main29main362
main30main233
main31main152
main32main163
main33main154
main34main153
main35main363
main36main341
main37main126
main38main127
main40main365
oldnewcomment
main41main131
main42main132
main43main133
main44main134joined
main45main134joined
main46main136
main48main364
main51main201
main52main202
main53main204
main54main203
main55main506
main61main325
main62main246
main63main261
main64main125
main68main342
main69main343
main70main344
main71main212
main72main213
main73main214
main74main215
main75main507
main76main508
main77main326
main78main345
main80main162joined
main81removed
main82main161
main83removed
main84removed
main85main162joined
main86main162joined
main87main162joined
main88main162joined
main89main164
main91main143
main92removed
oldnewcomment
main93main144
main94main141
main95main142
main101main441
main102main442
main103main248
main111main421
main112main422
main113main423
main121main262
main151main461
main152main462
main153main463
main154main464
main155main465
main156main466
main157main467
main158main468
main161main221
main162main222
main163main223
main171main509
main181main481
main182main482
main183main483
main184main484
main185main485
main200main401
main201main402
main202main403
main204main404
main205main405
main206main406
main207main407
main208main408
main280main162joined
main300main224
main301main263
main333main247



Table for the translation from the old Python names to the new ones:

oldnew
main01.pymain291.py
main10.pymain293.py
main34.pymain295.py
main39.pymain294.py
main162.pymain292.py