direforpythia is hosted by Hepforge, IPPP Durham

Documentation



Introduction

Thanks for your interest in DIRE (short for dipole resummation), a C++ program for all-order radiative corrections to scattering processes in high-energy particle collisions. The DIRE parton shower combines dipole-shower ideas in the spirit of ARIADNE with the careful handling of collinear enhancements in classical parton showers. As such, it is a full-fledged replacement of the PYTHIA8 parton showers for lepton-lepton, lepton-hadron and hadron-hadron collisions, including a detailed treatment of mass effects.

The DIRE physics publication is HERE or HERE. Please cite this article (and of course the PYTHIA8 reference) if you use PYTHIA8+DIRE for your research. Recent talks about DIRE can be found here and here.


Tutorial

If you are eager to get started with DIRE, you can check out this beginner's tutorial: worksheet1500.pdf.


Code documentation

The DIRE plugin for PYTHIA8 is implemented in accorrdance with the rules of implementing new parton showers for PYTHIA8. Thus, the code structure is very similar to PYTHIA8. Also, (almost) all input settings are reclycled from PYTHIA8. In the following, we will first document DIRE-specific input settings and then discuss the code structure.

Input settings

DIRE currently has only very few switches, so that a sophisticated documentation is not yet necessary. Thus, we simply list the DIRE-specific handles here.

ShowerPDF:usePDFalphas = on / off

This switch is turned off by default. Turned on, the alphaS running and thresholds will be directly taken from the PDF set interfaced through LHAPDF6. This can be helpful when validating the code, but will lead to a longer run time.

ShowerPDF:usePDFmasses = on / off

This switch is turned on by default. Turned on, quark masses will be directly taken from the PDF set interfaced through LHAPDF6.

ShowerPDF:useSummedPDF = on / off

This switch is turned on by default. Turned on, this means that the PDF ratios that are used in the evolution once an initial state parton partakes in a branching include both sea and valence quark contributions (if applicable).

DireSpace:useGlobalMapIF = on / off

This switch is turned off by default. Turned on, this means that the phase space of intial state emissions with a final state spectator is setup such that all final state particles share the momentum recoil of the emission.

DireSpace:forceMassiveMap = on / off

This switch is turned off by default. Turned on, this means that initial state emissions are allowed masses. This means the shower produces the awkward situation that incoming quarks are massless, but yield a assive final state quark upon conversion to an incoming gluon.

DireSpace:nFinalMax = n

where n is an integer value, and set to -10 by default. The spacelike showers will stop if this number of final state particles is reached.

DireTimes:nFinalMax = n

where n is an integer value, and set to -10 by default. The timelike showers will stop if this number of final state particles is reached.

Variations:doVariations = on / off

This switch is turned off by default. Turned on, this means that the timelike and spacelike showers are allowed to perform on-the-fly variations of the renormalization scale. Renormalization scale uncertainties are an important part of the perturbative evolution. Note that currently, these variations will also apply to showers off (soft) secondary scatterings. The range of renormalization scale variations is given by the next four parameters.

Variations:muRisrDown = k

The (double) value with which the (GeV2-valued) argument of αs in initial-state evolution should be rescaled to produce a smaller value of the renormalization scale in the context of automatic variations.

Variations:muRisrUp = k

The (double) value with which the (GeV2-valued) argument of αs in initial-state evolution should be rescaled to produce a larger value of the renormalization scale in the context of automatic variations.

Variations:muRfsrDown = k

The (double) value with which the (GeV2-valued) argument of αs in final-state evolution should be rescaled to produce a smaller value of the renormalization scale in the context of automatic variations.

Variations:muRfsrUp = k

The (double) value with which the (GeV2-valued) argument of αs in final-state evolution should be rescaled to produce a larger value of the renormalization scale in the context of automatic variations.


Further settings related to timelike showers can be found under on the DIRE Timelike evolution.

Further settings related to timelike showers can be found under on the DIRE Spacelike evolution.

All other settings are taken from PYTHIA8, keeping their meaning. The PYTHIA8 documentation can be found on the PYTHIA homepage.


Code structure

DIRE closely follows the rules outlined in the "Implement New Showers" section of the PYTHIA8 manual. The evolution thus proceeds roughly as follows:
  1. Initialise the shower with the init function.
  2. Set up the state for showering with the prepare and setupQCDdip functions. If this is not the first shower step, the function update will be used instead of prepare.
  3. Propose the next evolution step with pTnext (both in ISR and FSR). Through this function, the shower has already picked probabilistically among all possibly branchings, using the Sudakov veto algorithm. PYTHIA8 then decides if this evolution step wins out over multiparton interactions.
  4. If the DIRE step has not been picked, then restart the evolution of the new state at the evolution scale at which PYTHIA8 decided to change the state, i.e. continue from step 2.
  5. If the DIRE step has been chosen, generate the new state by inferring the branch function.
  6. Restart from step 2

One main construction difference is the way that branching functions are handled. For maximal modularity, no overestimates or splitting kernels are hard-coded in the timelike or spacelike showers. Instead, DIRE loads a library of splitting kernel objects upon initialisation. The default splitting library used in DIRE is assembled in SplittingLibrary.cc, which uses Splitting class objects as an input. All massless and massive QCD splitting kernels are available in SplittingsQCD.cc. New splitting kernels can be implemented in DIRE by deriving from the Splitting class defined in Splittings.h.

Note further that DIRE works with a weighted parton shower, as some splitting kernels are not positive definite in the soft gluon limit. This means that after showering, events may contain a non-unit weight. This weight is handled in the WeightContainer class. The necessary weight that has to be used for histogramming can be obtained from the getShowerWeight() function of the WeightContainer class.


Update notes

Updates in version 1.500

Version 1.500 should be considered a significant update over 0.900. The code has been consolidated from the first public version. Unfortunately, this will mean some level of backward incompatibility.
  1. The code has been restructured to follow good Unix practise, with include/Dire/ containing header files, and src/ containing sources. The new plugind/ directory is aimed at holding user extensions of the DIRE code.
  2. The files Splittings.h and Splittings.cc now only include the Splittings base class. All QCD kernels are now contained within SplittingsQCD.h and SplittingsQCD.cc. New QED and EW splitting functions have been added, though the respective code must be considered in development and is currently not used by the showers.
  3. Multiple bug fixes related to LHAPDF, the treatment of discarded events, and when running DIRE for minimum bias events. Thanks to Philip Ilten for bringing some of these to my attention!
  4. DIRE now offers automatic renormalization scale variations. This feature can be controlled with the 'doVariations' option. dire03.cc is a new main program illustrating this feature.
  5. DIRE includes two more new main programs. dire04.cc shows how to produce ProMC events, while dire05.cc is designed to easily load and organize PYTHIA analyses.