## Sample Main Programs

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.
- `main225.cc` : demonstrates how to use the `RivetHooks` plugin and run RIVET analyses, both with a single Pythia instance and `PythiaParallel`.

### 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` (new) : runs the same analysis as `main263.cc` but only for flavor hadronization parameters and demonstrates post-hoc reweighting rather than in-situ.
- `main265.cc` (new) : runs the same analysis as `main263.cc` but only for kinematic hadronization parameters and demonstrates post-hoc reweighting rather 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.
- `main303.cc` (new) : variations of effective shower kernels in LEP1 hadronic events, with option for parallel runs using OpenMP.

### 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.
- `main368.cc` (new) : plot the weight factors of [Fad90] in the production of t-tbar pairs. This allows also for below-threshold contributions, corresponding to the influence of short-lived toponium-like states.
- `main369.cc` (new) : study a few event properties in t-tbar production, comparing several alternatives constructed from the equations in [Fad90]. Demonstrates parallel running with OpenMP.
- `main370.cc` (new) : same as `main369` but uses `PythiaParallel` for parallel running of the analysis.
- `main371.cc` (new) : study several event properties in t-tbar production, from (by default) the most likely of the alternatives constructed from the equations in [Fad90].
- `main372.cc` (new) : study angular distributions in t-tbar production and decay, specifically between two final leptons in decay channels t → b W → b l nu (+corresponding for tbar), with or without the t-tbar-correlated decay matrix element.

### 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.
- `main484.cc` (was `main184.cc`) : simple example of how `PythiaCascade` can be used to simulate a basic hadronic cascade in a few simple atmospheres as a sequence of hadron-hadron collisions.
- `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 |
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