## Dire Parton Showers

### Please note: Due to lack of person power, the Dire Shower code is currently not maintained by the Pythia team and may be removed in a future release.

The Dire parton shower combines dipole-shower ideas in the spirit of Ariadne with the careful handling of collinear enhancements in classical parton showers. It includes a detailed treatment of mass effects and various higher-order corrections. The Dire parton shower is developed jointly in Pythia and Sherpa to allow maximal validation. The Dire physics publication is arxiv:1506.05057 [hep-ph]. Please cite this article (and of course the Pythia 8 reference) if you use Pythia 8 + Dire for your research.

Dire is a complete replacement for the default showers in Pythia, and is automatically interleaved with Pythia's multiple interaction model. At present, Dire offers:

- QCD and QED showers with automatic uncertainties and the possiblity to enhance individual splittings.
- Inclusive next-to-leading order DGLAP corrections to the shower evolution.
- Next-to-leading order final-state showering for lepton colliders.
- Iterated Matrix-Element corrections for splittings within the parton-shower phase space.

It is worth noting that Dire is constructed as as weighted parton shower, meaning that all events that are produced with Dire acquire a weight close to, but not identical to, unity. These weights need to be included when filling histograms or storing events. These weights can, conveniently combined with other weights (due to weighted LHEF inputs, merging etc.), be retrieved from `pythia.info.weight()`.

The following discusses some basic settings that might be of interest. Some convenience features are discussed here, while expert features (mainly aimed at comparisons of Dire to analytic calculations) are documented here.

`mode` DireTimes:kernelOrder (`default = 1`; `minimum = -1`; `maximum = 4`)
This setting defines which higher-order corrections are applied to the parton-shower splitting functions used for timelike (i.e. final state) evolution:
`option` -1 : Double-logarithmic kernels only, i.e. only gluon emissions, and no collinear terms or gluon-to-quark branchings. This setting is only intended to compare the parton shower to leading-logarithmic analytical resummation.
`option` 0 : Leading order evolution kernels, as defined in the original Dire publication.
`option` 1 : Leading order evolution kernels, and additional rescaling of the soft pieces to incorporate two-loop cusp efects (similar to the CMW scheme).
`option` 2 : Leading order evolution kernels, and additional rescaling of the soft pieces to incorporate two- and three-loop cusp efects.
`option` 3 : Leading order evolution kernels, additional rescaling of the soft pieces to incorporate two- and three-loop cusp efects, and NLO corrections to collinear evolution from NLO DGLAP kernels.

`mode` DireSpace:kernelOrder (`default = 1`; `minimum = -1`; `maximum = 4`)
This setting defines which higher-order corrections are applied to the parton-shower splitting functions used for spacelike (i.e. initial state) evolution:
`option` -1 : Double-logarithmic kernels only, i.e. only gluon emissions, and no collinear terms or gluon-to-quark branchings. This setting is only intended to compare the parton shower to leading-logarithmic analytical resummation.
`option` 0 : Leading order evolution kernels, as defined in the original Dire publication.
`option` 1 : Leading order evolution kernels, and additional rescaling of the soft pieces to incorporate two-loop cusp efects (similar to the CMW scheme).
`option` 2 : Leading order evolution kernels, and additional rescaling of the soft pieces to incorporate two- and three-loop cusp efects.
`option` 3 : Leading order evolution kernels, additional rescaling of the soft pieces to incorporate two- and three-loop cusp efects, and NLO corrections to collinear evolution from NLO DGLAP kernels.

`mode` DireTimes:kernelOrderMPI (`default = 1`; `minimum = -1`; `maximum = 4`)
Same as DireTimes:kernelOrder = n, but for showers from secondary scatterings or hadron decays.

`mode` DireSpace:kernelOrderMPI (`default = 1`; `minimum = -1`; `maximum = 4`)
Same as DireSpace:kernelOrder = n, but for showers from secondary scatterings or hadron decays.

`parm` DireTimes:pTrecombine (`default = 2.0`)
The minimal pT value t (in GeV) of final-state emissions below which the splitting probabilities of some kernels are combined into a single splitting probability. To be more precise, for pT<t, the probabilities for q->qg and q->gq are combined into a single probability, as are g->qqbar and g->qbarq and the two color structures for g->gg. This can help improve the numerical stability of the Sudakov veto algorithm, however at the expense accuracy. Negative values mean that variations are performed for all parton shower emissions. Default value is 2.0 GeV.

### Settings related to the evaluation of running (QCD) couplings

`flag` ShowerPDF:usePDFalphas (`default = 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.

### Settings to perform variations to gauge shower uncertainties

`flag` Variations:doVariations (`default = off`)
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.

`parm` Variations:muRisrDown (`default = 1.0`)
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.

`parm` Variations:muRisrUp (`default = 1.0`)
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.

`parm` Variations:muRfsrDown (`default = 1.0`)
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.

`parm` Variations:muRfsrUp (`default = 1.0`)
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.

`parm` Variations:pTmin (`default = -1.0`)
The minimal pT value t (in GeV) of emissions below which no parton shower variations are considered. Negative values mean that variations may be performed for emissions at any pT. Default value is -1.0 GeV.

The following settings are currently under investigation and not used in the code.

`mode` Variations:PDFmemberMin (`default = -1`)

`mode` Variations:PDFmemberMax (`default = -1`)

`flag` Variations:PDFup (`default = off`)

`flag` Variations:PDFdown (`default = off`)

### Settings related to parton distribution functions and quark masses

`flag` ShowerPDF:usePDFmasses (`default = on`)
Turned on, quark masses will be directly taken from the PDF set interfaced through LHAPDF6.

`flag` ShowerPDF:usePDF (`default = on`)

`flag` ShowerPDF:useSummedPDF (`default = on`)
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).

`flag` DireSpace:useGlobalMapIF (`default = off`)
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.

`flag` DireSpace:forceMassiveMap (`default = off`)
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.

### Settings related to the tune of Pythia 8 + Dire

`mode` Dire:Tune (`default = 1`; `minimum = -1`)
If set to one, this enables the default tune of Pythia8 + Dire. Currently, all other values mean that no Pythia parameters are automatically overwritten by Dire.

### Settings for debugging or educational purposes

`mode` DireSpace:nFinalMax (`default = -10`; `minimum = 0`)
The spacelike showers will stop if this number of final state particles is reached.

`mode` DireTimes:nFinalMax (`default = -10`; `minimum = 0`)
The timelike showers will stop if this number of final state particles is reached.