PYTHIA 8

Welcome to PYTHIA - The Lund Monte Carlo!
Documentation
Authors
Former authors
Further contributions
Contact
Licence

Welcome to PYTHIA - The Lund Monte Carlo!

PYTHIA is a general-purpose event generator for high-energy particle collisions. PYTHIA 8 is the successor to PYTHIA 6, rewritten from scratch in C++. It includes many new features, but rests on the same historical physics base, including concepts such as soft and hard processes, parton showers, multiparton interactions and string fragmentation. With the current PYTHIA 8.3 version the step has been taken from C++98 to C++11, but the transition from 8.2 should largely be transparent to users. Also several new physics features are made available.

Documentation

On these webpages you will find the HTML manual for PYTHIA 8.3. The physics descriptions may in places need to be updated, but the documentation of available settings and other practical details should be fully up-to-date. Use the left-hand index to navigate this documentation of program elements, especially of all possible program settings. All parameters are provided with sensible default values, however, so you need only change those of relevance to your particular study, such as choice of beams, processes and phase space cuts. The pages also contain a fairly extensive survey of all methods available to the user, e.g. to study the produced events.

What these pages are not very well suited to give you, is a comprehensive explanation of choices made and the physics behind them. For that, we refer the reader to:
A comprehensive guide to the physics and usage of PYTHIA 8.3
C. Bierlich et al, SciPost Phys. Codebases 8-r8.3 (2022) [arXiv:2203.11601 [hep-ph]].

We ask that you cite this publication, when using PYTHIA 8.3. Older documentation still exists, and could be useful in particular from users transitioning from older versions of PYTHIA. An overview of PYTHIA 8.2 can be found in the attached PDF file
An Introduction to PYTHIA 8.2
T. Sjöstrand et al, Comput. Phys.Commun. 191 (2015) 159 [arXiv:1410.3012 [hep-ph]].

The even older
PYTHIA 6.4 Physics and Manual
T. Sjöstrand, S. Mrenna and P. Skands, JHEP05 (2006) 026,
describes the physics of PYTHIA 6 in great detail, but is now superseeded by the PYTHIA 8.3 manual.

Furthermore, a separate
PYTHIA 8.3 Worksheet,
also an attached PDF file, offers a practical introduction to using the generator. It has been developed for and used at a few summer schools, with minor variations, but is also suited for self-study.

Authors

Javira Altmann
School of Physics and Astronomy, Monash University, PO Box 27, 3800 Melbourne, Australia
e-mail: javira.altmann@monash.edu

Christian Bierlich
Department of Physics, Lund University, Box 118, SE-221 00 Lund, Sweden
e-mail: christian.bierlich@fysik.lu.se

Naomi Cooke
School of Physics and Astronomy, University of Glasgow, Glasgow G12 8QQ, Scotland, United Kingdom
e-mail: naomi.cooke@cern.ch

Nishita Desai
Department of Theoretical Physics, Tata Institute of Fundamental Research, Homi Bhabha Road, Mumbai 400005, India
e-mail: desai@theory.tifr.res.in

Leif Gellersen
Department of Physics, Lund University, Box 118, SE-221 00 Lund, Sweden
e-mail: leif.gellersen@fysik.lu.se

Ilkka Helenius
Department of Physics, University of Jyväskylä, P.O. Box 35, FI-40014 University of Jyväskylä, Finland
e-mail: ilkka.m.helenius@jyu.fi

Philip Ilten
Department of Physics, University of Cincinnati, Cincinnati, OH 45221, USA
e-mail: philten@cern.ch

Leif Lönnblad
Department of Physics, Lund University, Box 118, SE-221 00 Lund, Sweden
e-mail: leif.lonnblad@fysik.lu.se

Stephen Mrenna
Computing Division, Simulations Group, Fermi National Accelerator Laboratory, MS 234, Batavia, IL 60510, USA
e-mail: mrenna@fnal.gov

Christian Preuss
Institute for Theoretical Physics, ETH Zürich, Wolfgang-Pauli-Strasse 27, 8093 Zürich, Switzerland
e-mail: cpreuss@phys.ethz.ch

Torbjörn Sjöstrand
Department of Physics, Lund University, Box 118, SE-221 00 Lund, Sweden
e-mail: torbjorn.sjostrand@fysik.lu.se

Peter Skands
School of Physics and Astronomy, Monash University, PO Box 27, 3800 Melbourne, Australia
e-mail: peter.skands@monash.edu

Marius Utheim
Department of Physics, University of Jyväskylä, P.O. Box 35, FI-40014 University of Jyväskylä, Finland
e-mail: marius.m.utheim@jyu.fi

Rob Verheyen
Department of Physics and Astronomy, University College London, Gower St, Bloomsbury, London WC1E 6BT, UK
e-mail: r.verheyen@ucl.ac.uk

Former authors

Stefan Ask

Jesper Roy Christiansen

Richard Corke

Nadine Fischer

Stefan Prestel

Christine O. Rasmussen

Further contributions

HepMC interface by Mikhail Kirsanov.
Conversion of XML files to PHP ones by Ben Lloyd.
Simple Makefile for Win32/NMAKE by Bertrand Bellenot.
Extended Higgs sector partly implemented by Marc Montull.
Parts of charm and bottom decay tables courtesy DELPHI and LHCb collaborations.
Tunes and comparisons with data, based on Rivet and Professor, by Hendrik Hoeth.
Text and code on the use of ROOT in conjunction with PYTHIA by Rene Brun, Andreas Morsch and Axel Naumann.
Code and data for MRST/MSTW PDFs by Robert Thorne and Graeme Watt.
Code and data for the CTEQ/CT PDFs by Joey Huston and colleagues.
Help with implementing new proton PDFs by Tomas Kasemets.
Code and data for Pomeron PDFs by H1 collaboration and especially Paul Newman.
Help with implementing new Pomeron fluxes and PDFs by Sparsh Navin.
The new Hidden Valley code developed together with Lisa Carloni.
Code for a Kaluza-Klein electroweak gauge boson provided by Noam Hod and Mark Sutton.
Code for equivalent photon flux around an unresolved proton by Oystein Alvestad.
The MBR diffractive model and central diffraction by Robert Ciesielski.
2012 branching ratios for most light hadrons, and the tau lepton, by Anil Pratap Singh.
The pythia8-config script has been contributed by Andy Buckley, along with many other helpful suggestions.
Code and data for several of the NNPDF2.3 QCD+QED sets, and further later ones, provided by Juan Rojo and Stefano Carrazza.
The fjcore code from FastJet provided by Matteo Cacciari, Gavin Salam and Gregory Soyez.
The initial-final dipole approach has been developed and implemented by Baptiste Cabouat.
The MixMax random number generator has been contributed by Konstantin Savvidy and George Savvidy.
Space-time hadronic production points in string fragmentation have been studied and implemented by Silvia Ferreres-Solé.
The code for deuteron production was tested by Sophie Baker.
C++ interface to MG5 matrix elements by V. Hirschi with additional work by O. Mattelaer.
Mass corrections and initial-state showers in Vincia by M. Ritzmann.
Final-state sector showers in Vincia by J. Lopez-Villarejo.
Helicity-dependence in Vincia by A. Larkoski.
Interleaved resonance showers and work on MESS merging and QED+EW showers in Vincia by H. Brooks.
Plugin and hadronization reweighting framework by the MLhad team.
Mini-junction string improvements and additions to the QCD-based colour reconnection model by Harsh Shah.

Note: in several cases modifications have been made to the original code, in order to integrate it with PYTHIA. In these cases the blame for any mistakes has to rest with the regular authors.

Contact

New version alerts

If you want to be alerted whenever a new public version is released, you can subscribe on pythia8-announce. Expect a handful of such messages per year. There is no fixed schedule; new versions can appear either because a sufficient amount of changes have been accumulated over time, or because some crucial new feature or bug fix prompts action.

Bug reports and physics questions

No code is perfect, and we rely on PYTHIA users to report suspect behaviour to us. We are starting to collect common questions and problems with our issue tracker. Please check this resource first for answered questions. New questions and issues can be either opened with a freely available gitlab.com account or emailing us at authors@pythia.org where no account is required. To help us in the subsequent debugging efforts, however, it is helpful if you can present your case in as clear terms as possible. A convenient path is the following.

Users often combine PYTHIA with a set of other libraries in their studies, and then problems originally attributed to PYTHIA usually turn out to be located somewhere else. Therefore, check that the problem remains if no other libraries are being used. If you want to file a report that involves other libraries please have a very convincing case that the problem is in PYTHIA to be taken seriously.
Make sure you use a clean copy of PYTHIA, not one that has been subject to "local modifications" by parties unknown. Also make sure it is a recent one - you may have encountered a true bug, but one already solved in the current version. If uncertain, pick up a new copy directly from the PYTHIA webpage, and create a new cleanly compiled PYTHIA library code.
Write a simple standalone main program mymainNN.cc, with NN between 00 and 99, that demonstrates the claimed bug. Feel free to use some of the existing sample main programs share/Pythia8/examples/mainNNN.cc as templates.
Put the mymainNN.cc program in the share/Pythia8/examples subdirectory and run it from there (make mymainNN followed by ./mymainNN).
Now, systematically peel away all irrelevant code in the main program, so that only code really needed to reproduce and document the bug remains. Where explanations in the code would be helpful, do add comments in English.
Send the main program, with a description what is the problem and whatever guesses you may have about a probable cause.

Note, the email authors@pythia.org should always be used when contacting the authors as it allows us to coordinate replies. You may also include the individual addresses of authors that are relevant for a specific issue. Never contact several persons independently on the same topic, thereby potentially leading to doublework. Abuse will have consequences.

When responding to emails from us at authors@pythia.org, reply directly to the email, which has a unique return address of the form incoming+<hash>@incoming.gitlab.com, and not authors@pythia.org. Please consider allowing your correspondence to be made publicly available to other users via our issue tracker, by replying at any point with your express permission, e.g. "this correspondence can be made public".

Do note that the major collaborations, such as ATLAS and CMS, have their own Monte Carlo support groups, with a lot of experience in solving typical issues, many of which are related to the setups and interfaces created inside the collaborations. If you are a member of a major collaboration you please turn to these groups in the first place, and only turn to us when it has been confirmed as a true problem going beyond the local installation.

Licence

PYTHIA 8 is licensed under the GNU General Public Licence version 2 or later.
Please respect the MCnet Guidelines for Event Generator Authors and Users.