Routines and Common-Block Variables

In this section we collect information on how to use the initial- and final-state showering routines. Of these PYSHOW for final-state radiation is the more generally interesting, since it can be called to let a user-defined parton configuration shower. The same applies for the new PYPTFS routine. PYSSPA, on the other hand, is so intertwined with the general structure of a PYTHIA event that it is of little use as a stand-alone product, and so should only be accessed via PYEVNT. Similarly PYPTIS should not be called directly. Instead PEVNW should be called, which in its turn calls PYEVOL for the interleaved evolution of initial-state radiation with PYPTIS and multiple interactions with PYPTMI.

Purpose:

to generate time-like parton showers, conventional or coherent. The performance of the program is regulated by the switches MSTJ(38) - MSTJ(50) and parameters PARJ(80) - PARJ(90). In order to keep track of the colour flow information, the positions K(I,4) and K(I,5) have to be organized properly for showering partons. Inside the PYTHIA programs, this is done automatically, but for external use proper care must be taken.

IP1 > 0, IP2 = 0 :

generate a time-like parton shower for the parton in line IP1 in common block PYJETS, with maximum allowed mass QMAX. With only one parton at hand, one cannot simultaneously conserve both energy and momentum: we here choose to conserve energy and jet direction, while longitudinal momentum (along the jet axis) is not conserved.

IP1 > 0, IP2 > 0 :

generate time-like parton showers for the two partons in lines IP1 and IP2 in the common block PYJETS, with maximum allowed mass for each parton QMAX. For shower evolution, the two partons are boosted to their c.m. frame. Energy and momentum is conserved for the pair of partons, although not for each individually. One of the two partons may be replaced by a nonradiating particle, such as a photon or a diquark; the energy and momentum of this particle will then be modified to conserve the total energy and momentum.

IP1 > 0, -80 $\leq$ IP2 < 0 :

generate time-like parton showers for the -IP2 (at most 80) partons in lines IP1, IP1+1, ...IPI-IP2-1 in the common block PYJETS, with maximum allowed mass for each parton QMAX. The actions for IP2 = -1 and IP2 = -2 correspond to what is described above, but additionally larger numbers may be used to generate the evolution starting from three or more given partons. Then the partons are boosted to their c.m. frame, the direction of the momentum vector is conserved for each parton individually and energy for the system as a whole. It should be understood that the uncertainty in this option is larger than for two-parton systems, and that a number of the sophisticated features (such as coherence with the incoming colour flow) are not implemented.

IP1 > 0, IP2 = -100 :

generate a four-parton system, where a history starting from two partons has already been constructed as discussed in section . Including intermediate partons this requires 8 lines. This option is used in PY4JET, whereas you would normally not want to use it directly yourself.

QMAX :

the maximum allowed mass of a radiating parton, i.e. the starting value for the subsequent evolution. (In addition, the mass of a single parton may not exceed its energy, the mass of a parton in a system may not exceed the invariant mass of the system.)

Purpose:

to generate a $p_{\perp}$-ordered time-like final-state parton shower. The performance of the program is regulated by the switches MSTJ(38), MSTJ(41), MSTJ(45), MSTJ(46) and MSTJ(47), and parameters PARJ(80) PARJ(81), PARJ(82), PARJ(83) and PARJ(90), i.e. only a subset of the ones available with PYSHOW. In order to keep track of the colour flow information, the positions K(I,4) and K(I,5) have to be organized properly for showering partons. Inside the PYTHIA programs, this is done automatically, but for external use proper care must be taken.

NPART :

the number of partons in the system to be showered. Must be at least 2, and can be as large as required (modulo the technical limit below). Is updated at return to be the new number of partons, after the shower.

IPART :

array, of dimension 500 (cf. the Les Houches Accord for user processes), in which the positions of the relevant partons are stored. To allow the identification of matrix elements, (the showered copies of) the original resonance decay products, if any, should be stored in the first two slots, IPART(1) and IPART(2). Is updated at return to be the new list of partons, by adding new particles at the end. Thus, for $\mathrm{q}\to \mathrm{q}\mathrm{g}$ the quark position is updated and the gluon added, while for $\mathrm{g}\to \mathrm{g}\mathrm{g}$ and $\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}$ the choice of original and new is arbitrary.

PTMAX :

upper scale of shower evolution. An absolute limit is set by kinematical constraints inside each `dipole'.

PTMIN :

lower scale of shower evolution. For QCD evolution, an absolute lower limit is set by PARJ(82)/2 or $1.1 \times \Lambda_{\mathrm{QCD}}^{(3)}$, whichever is larger. For QED evolution, an absolute lower limit is set by PARJ(83)/2 or PARJ(90)/2. Normally one would therefore set PTMIN = 0D0 to run the shower to its intended lower cutoff.

PTGEN :

returns the hardest $p_{\perp}$ generated; if none then PTGEN = 0.

Note 1:

the evolution is factorized, so that a set of successive calls, where the PTMIN scale and the NPART and IPART output of one call becomes the PTMAX scale and the NPART and IPART input of the next, gives the same result (on the average) as one single call for the full $p_{\perp}$ range. In particular, the IPART(1) and IPART(2) entries continue to point to (the showered copies of) the original decay products of a resonance if they did so to begin with.

Note 2:

in order to read a shower listing, note that each branching now lists three `new' partons. The first two are the daughters of the branching, and point back to the branching mother. The third is the recoiling parton after it has taken the recoil, and points back to itself before the recoil. The total energy and momentum is conserved from the mother and original recoil to the three new partons, but not separately between the mother and its two daughters.

Note 3:

the shower is not (yet) set up to allow showers with a fixed $\alpha_{\mathrm{s}}$ nor handle radiation in baryon-number-violating decays. Neither is there any provision for models with a scalar gluon or Abelian vector gluons.

Note 4:

the PYPTFS can also be used as an integrated element of a normal PYTHIA run, in places where PYSHOW would otherwise be used. This is achieved by setting MSTJ(41) = 11 or = 12. Then PYSHOW will call PYPTFS, provided that the showering system consists of at least two partons and that the forced four-parton-shower option is not used (IP2 = -100). PTMAX is then chosen to be half of the QMAX scale of the PYSHOW call, and PTMIN is chosen to zero (which means the default lower limits will be used). This works nicely e.g. in $\mathrm{e}^+\mathrm{e}^-$ annihilation and for resonance decays. Currently it is not so convenient for hadronic events: there is not yet a matching to avoid double-counting between initial- and final-state radiation, and sidebranch time-like evolution in space-like showers is currently handled by evolving one parton with PYSHOW, which PYPTFS is not set up for.

Note 5:

for simplicity, all partons are evolved from a common PTMAX scale. The formalism easily accommodates separate PTMAX scales for each parton, but we have avoided this for now so as not to complicate the routine unnecessarily for general use.

Purpose:

returns the ratio of the first-order gluon emission rate normalized to the lowest-order event rate, eq. (). An overall factor $C_F \alpha_{\mathrm{s}}/2\pi$ is omitted, since the running of $\alpha_{\mathrm{s}}$ probably is done better in shower language anyway.

NI :

code of the matrix element to be used, see Table . In each group of four codes in that table, the first is for the 1 case, the second for the $\gamma_5$ one, the third for an arbitrary mixture, see ALPHA below, and the last for $1 \pm \gamma_5$.

X1, X2 :

standard energy fractions of the two daughters.

R1, R2 :

mass of the two daughters normalized to the mother mass.

ALPHA:

fraction of the no-$\gamma_5$ (i.e. vector/scalar/...) part of the cross section; a free parameter for the third matrix element option of each group in Table  (13, 18, 23, 28, ...).

Purpose:

to administrate a sequence of final-state showers for external processes, where the order normally is that all resonances have decayed before showers are considered, and therefore already existing daughters have to be boosted when their mothers radiate or take the recoil from radiation.

NFIN :

line in the event record of the last final-state entry to consider.

Purpose:

to generate the space-like showers of the initial-state radiation in the `old', virtuality-ordered model. The performance of the program is regulated by the switches MSTP(61) - MSTP(69) and parameters PARP(61) - PARP(68).

IPU1, IPU2 :

positions of the two partons entering the hard scattering, from which the backwards evolution is initiated.

Purpose:

to generate the space-like showers of the initial-state radiation in the `new', transverse-momentum-ordered model. The performance of the program is regulated by the switches MSTP(61), MSTP(62), MSTP(68), MSTP(69), MSTP(70) and MSTP(72), and parameters PARP(61), PARP(62) and PARP(64) i.e. only a subset of the ones available with PYSSPA, but also with a few new extensions.

MODE :

whether initialization ($-1$), trial emission ($0$) or kinematics of accepted branching ($+1$).

PT2NOW :

starting (max) $p_{\perp}^2$ scale for evolution.

PT2CUT :

lower limit for evolution.

PT2 :

result of evolution. Generated $p_{\perp}^2$ for trial emission.

IFAIL :

status return code. IFAIL = 0 when all is well.

Note:

a few non-standard options have not been implemented, such as evolution with fixed $\alpha_{\mathrm{s}}$.

Purpose:

to set the maximum of the ratio of the correct matrix element to the one implied by the space-like parton shower.

MECOR :

kind of hard-scattering process, 1 for $\mathrm{f}+ \overline{\mathrm{f}}\to \gamma^*/\mathrm{Z}^0/\mathrm{W}^{\pm}/\ldots$ vector gauge bosons, 2 for $\mathrm{g}+ \mathrm{g}\to \mathrm{h}^0/\H ^0/\mathrm{A}^0$.

WTFF, WTGF, WTFG, WTGG :

maximum weights for $\mathrm{f}\to \mathrm{f}\, (+ \mathrm{g}/\gamma)$, $\mathrm{g}/\gamma \to \mathrm{f}\, (+ \overline{\mathrm{f}})$, $\mathrm{f}\to \mathrm{g}/\gamma \, (+ \mathrm{f})$ and $\mathrm{g}\to \mathrm{g}\, (+ \mathrm{g})$, respectively.

Purpose:

to calculate the ratio of the correct matrix element to the one implied by the space-like parton shower.

MECOR :

kind of hard-scattering process, 1 for $\mathrm{f}+ \overline{\mathrm{f}}\to \gamma^*/\mathrm{Z}^0/\mathrm{W}^{\pm}/\ldots$ vector gauge bosons, 2 for $\mathrm{g}+ \mathrm{g}\to \mathrm{h}^0/\H ^0/\mathrm{A}^0$.

IFLCB :

kind of branching, 1 for $\mathrm{f}\to \mathrm{f}\, (+ \mathrm{g}/\gamma)$, 2 for $\mathrm{g}/\gamma \to \mathrm{f}\, (+ \overline{\mathrm{f}})$, 3 for $\mathrm{f}\to \mathrm{g}/\gamma \, (+ \mathrm{f})$ and 4 for $\mathrm{g}\to \mathrm{g}\, (+ \mathrm{g})$.

Q2, Z :

$Q^2$ and $z$ values of shower branching under consideration.

PHIBR :

$\varphi$ azimuthal angle of the shower branching; may be overwritten inside routine.

WTME :

calculated matrix element correction weight, used in the acceptance/rejection of the shower branching under consideration.

Purpose:

to give access to a number of status codes and parameters which regulate the performance of PYTHIA. Most parameters are described in section ; here only those related to PYSHOW and PYPTFS are described.

MSTJ(38) :

(D = 0) matrix element code NI for PYMAEL; as in MSTJ(47). If nonzero, the MSTJ(38) value overrides MSTJ(47), but is then set = 0 in the PYSHOW or PYPTFS call. The usefulness of this switch lies in processes where sequential decays occur and thus there are several showers, each requiring its matrix element. Therefore MSTJ(38) can be set in the calling routine when it is known, and when not set one defaults back to the attempted matching procedure of MSTJ(47) = 3 (e.g.).

MSTJ(40) :

(D = 0) possibility to suppress the branching probability for a branching $\mathrm{q}\to \mathrm{q}\mathrm{g}$ (or $\mathrm{q}\to \mathrm{q}\gamma$) of a quark produced in the decay of an unstable particle with width $\Gamma$, where this width has to be specified by you in PARJ(89). The algorithm used is not exact, but still gives some impression of potential effects. This switch, valid for PYSHOW, ought to have appeared at the end of the current list of shower switches (after MSTJ(50)), but because of lack of space it appears immediately before.

= 0 :

no suppression, i.e. the standard parton-shower machinery.

= 1 :

suppress radiation by a factor $\chi(\omega) = \Gamma^2 / (\Gamma^2 + \omega^2)$, where $\omega$ is the energy of the gluon (or photon) in the rest frame of the radiating dipole. Essentially this means that hard radiation with $\omega > \Gamma$ is removed.

= 2 :

suppress radiation by a factor $1 - \chi(\omega) = \omega^2 / (\Gamma^2 + \omega^2)$, where $\omega$ is the energy of the gluon (or photon) in the rest frame of the radiating dipole. Essentially this means that soft radiation with $\omega < \Gamma$ is removed.

MSTJ(41) :

(D = 2) type of branchings allowed in shower.

= 0 :

no branchings at all, i.e. shower is switched off.

= 1 :

QCD type branchings of quarks and gluons.

= 2 :

also emission of photons off quarks and leptons; the photons are assumed on the mass shell.

= 3 :

QCD type branchings of quarks and gluons, and also emission of photons off quarks, but leptons do not radiate (unlike = 2). Is not implemented for PYPTFS.

= 10 :

as = 2, but enhance photon emission by a factor PARJ(84). This option is unphysical, but for moderate values, PARJ(84)$\leq 10$, it may be used to enhance the prompt photon signal in $\mathrm{q}\overline{\mathrm{q}}$ events. The normalization of the prompt photon rate should then be scaled down by the same factor. The dangers of an improper use are significant, so do not use this option if you do not know what you are doing. Is not implemented for PYPTFS.

= 11 :

QCD type branchings of quarks and gluons, like = 1, but if PYSHOW is called with a parton system that PYPTFS can handle, the latter routine is called to do the shower. If PYPTFS is called directly by the user, this option is equivalent to = 1.

= 12 :

also emission of photons off quarks and leptons, like = 2, but if PYSHOW is called with a parton system that PYPTFS can handle, the latter routine is called to do the shower. If PYPTFS is called directly by the user, this option is equivalent to = 2.

MSTJ(42) :

(D = 2) branching mode, especially coherence level, for time-like showers in PYSHOW.

= 1 :

conventional branching, i.e. without angular ordering.

= 2 :

coherent branching, i.e. with angular ordering.

= 3 :

in a branching $a \to b \mathrm{g}$, where $m_b$ is nonvanishing, the decay angle is reduced by a factor $(1 + (m_b^2/m_a^2) (1-z)/z)^{-1}$, thereby taking into account mass effects in the decay [Nor01]. Therefore more branchings are acceptable from an angular ordering point of view. In the definition of the angle in a $g \to \mathrm{q}\overline{\mathrm{q}}$ branchings, the naïve massless expression is reduced by a factor $\sqrt{1 - 4 m_q^2/m_g^2}$, which can be motivated by a corresponding actual reduction in the $p_{\perp}$ by mass effects. The requirement of angular ordering then kills fewer potential $\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}$ branchings, i.e. the rate of such comes up. The $\mathrm{g}\to \mathrm{g}\mathrm{g}$ branchings are not changed from = 2. This option is fully within the range of uncertainty that exists.

= 4 :

as = 3 for $a \to b \mathrm{g}$ and $\mathrm{g}\to \mathrm{g}\mathrm{g}$ branchings, but no angular ordering requirement conditions at all are imposed on $\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}$ branchings. This is an unrealistic extreme, and results obtained with it should not be overstressed. However, for some studies it is of interest. For instance, it not only gives a much higher rate of charm and bottom production in showers, but also affects the kinematical distributions of such pairs.

= 5 :

new `intermediate' coherence level [Nor01], where the consecutive gluon emissions off the original pair of branching partons is not constrained by angular ordering at all. The subsequent showering of such a gluon is angular ordered, however, starting from its production angle. At LEP energies, this gives almost no change in the total parton multiplicity, but this multiplicity now increases somewhat faster with energy than before, in better agreement with analytical formulae. (The PYSHOW algorithm overconstrains the shower by ordering emissions in mass and then vetoing increasing angles. This is a first simple attempt to redress the issue.) Other branchings as in = 2.

= 6 :

`intermediate' coherence level as = 5 for primary partons, unchanged for $\mathrm{g}\to \mathrm{g}\mathrm{g}$ and reduced angle for $\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}$ and secondary $\mathrm{q}\to \mathrm{q}\mathrm{g}$ as in = 3.

= 7 :

`intermediate' coherence level as = 5 for primary partons, unchanged for $\mathrm{g}\to \mathrm{g}\mathrm{g}$, reduced angle for secondary $\mathrm{q}\to \mathrm{q}\mathrm{g}$ as in = 3 and no angular ordering for $\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}$ as in = 4.

MSTJ(43) :

(D = 4) choice of $z$ definition in branchings in PYSHOW.

= 1 :

energy fraction in grandmother's rest frame (`local, constrained').

= 2 :

energy fraction in grandmother's rest frame assuming massless daughters, with energy and momentum reshuffled for massive ones (`local, unconstrained').

= 3 :

energy fraction in c.m. frame of the showering partons (`global, constrained').

= 4 :

energy fraction in c.m. frame of the showering partons assuming massless daughters, with energy and momentum reshuffled for massive ones (`global, unconstrained').

MSTJ(44) :

(D = 2) choice of $\alpha_{\mathrm{s}}$ scale for shower in PYSHOW.

= 0 :

fixed at PARU(111) value.

= 1 :

running with $Q^2 = m^2/4$, $m$ mass of decaying parton, $\Lambda$ as stored in PARJ(81) (natural choice for conventional showers).

= 2 :

running with $Q^2 = z(1-z)m^2$, i.e. roughly $p_{\perp}^2$ of branching, $\Lambda$ as stored in PARJ(81) (natural choice for coherent showers).

= 3 :

while $p_{\perp}^2$ is used as $\alpha_{\mathrm{s}}$ argument in $\mathrm{q}\to \mathrm{q}\mathrm{g}$ and $\mathrm{g}\to \mathrm{g}\mathrm{g}$ branchings, as in = 2, instead $m^2/4$ is used as argument for $\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}$ ones. The argument is that the soft-gluon resummation results suggesting the $p_{\perp}^2$ scale [Ama80] in the former processes is not valid for the latter one, so that any multiple of the mass of the branching parton is a perfectly valid alternative. The $m^2/4$ ones then gives continuity with $p_{\perp}^2$ for $z=1/2$. Furthermore, with this choice, it is no longer necessary to have the requirement of a minimum $p_{\perp}$ in branchings, else required in order to avoid having $\alpha_{\mathrm{s}}$ blow up. Therefore, in this option, that cut has been removed for $\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}$ branchings. Specifically, when combined with MSTJ(42) = 4, it is possible to reproduce the simple $1 + \cos^2\theta$ angular distribution of $\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}$ branchings, which is not possible in any other approach. (However it may give too high a charm and bottom production rate in showers [Nor01].)

= 4 :

$p_{\perp}^2$ as in = 2, but scaled down by a factor $(1 - m_b^2/m_a^2)^2$ for a branching $a \to b \mathrm{g}$ with $b$ massive, in an attempt better to take into account the mass effect on kinematics.

= 5 :

as for = 4 for $\mathrm{q}\to \mathrm{q}\mathrm{g}$, unchanged for $\mathrm{g}\to \mathrm{g}\mathrm{g}$ and as = 3 for $\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}$.

MSTJ(45) :

(D = 5) maximum flavour that can be produced in shower by $\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}$; also used to determine the maximum number of active flavours in the $\alpha_{\mathrm{s}}$ factor in parton showers (here with a minimum of 3).

MSTJ(46) :

(D = 3) nonhomogeneous azimuthal distributions in a shower branching.

= 0 :

azimuthal angle is chosen uniformly.

= 1 :

nonhomogeneous azimuthal angle in gluon decays due to a kinematics-dependent effective gluon polarization. Not meaningful for scalar model, i.e. then same as = 0.

= 2 :

nonhomogeneous azimuthal angle in gluon decay due to interference with nearest neighbour (in colour). Not meaningful for Abelian model, i.e. then same as = 0.

= 3 :

nonhomogeneous azimuthal angle in gluon decay due to both polarization (= 1) and interference (= 2). Not meaningful for Abelian model, i.e. then same as = 1. Not meaningful for scalar model, i.e. then same as = 2.

Note :

PYPTFS only implements nonhomogeneities related to the gluon spin, and so options 0 and 2 are equivalent, as are 1 and 3.

MSTJ(47) :

(D = 3) matrix-element-motivated corrections to the gluon shower emission rate in generic processes of the type $a \to bc\mathrm{g}$. Also, in the massless fermion approximation, with an imagined vector source, to the lowest-order $\mathrm{q}\overline{\mathrm{q}}\gamma$, $\ell^+\ell^-\gamma$ or $\ell\nu_{\ell}\gamma$ matrix elements, i.e. more primitive than for QCD radiation.

= 0 :

no corrections.

= 1 - 5 :

yes; try to match to the most relevant matrix element and default back to an assumed source (e.g. a vector for a $\mathrm{q}\overline{\mathrm{q}}$ pair) if the correct mother particle cannot be found.

= 6 - :

yes, match to the specific matrix element code NI = MSTJ(47) of the PYMAEL function; see Table .

Warning :

since a process may contain sequential decays involving several different kinds of matrix elements, it may be dangerous to fix MSTJ(47) to a specialized value $>5$; see MSTJ(38) above.

MSTJ(48) :

(D = 0) possibility to impose maximum angle for the first branching in a PYSHOW shower.

= 0 :

no explicit maximum angle.

= 1 :

maximum angle given by PARJ(85) for single showering parton, by PARJ(85) and PARJ(86) for pair of showering partons.

MSTJ(49) :

(D = 0) possibility to change the branching probabilities in PYSHOW according to some alternative toy models (note that the $Q^2$ evolution of $\alpha_{\mathrm{s}}$ may well be different in these models, but that only the MSTJ(44) options are at your disposal).

= 0 :

standard QCD branchings.

= 1 :

branchings according to a scalar gluon theory, i.e. the splitting kernels in the evolution equations are, with a common factor $\alpha_{\mathrm{s}}/(2\pi)$ omitted, $P_{\mathrm{q}\to \mathrm{q}\mathrm{g}} = (2/3) (1-z)$, $P_{\mathrm{g}\to \mathrm{g}\mathrm{g}} =$ PARJ(87), $P_{\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}} =$ PARJ(88) (for each separate flavour). The couplings of the gluon have been left as free parameters, since they depend on the colour structure assumed. Note that, since a spin 0 object decays isotropically, the gluon splitting kernels contain no $z$ dependence.

= 2 :

branchings according to an Abelian vector gluon theory, i.e. the colour factors are changed (compared with QCD) according to $C_F = 4/3 \to 1$, $N_C = 3 \to 0$, $T_R = 1/2 \to 3$. Note that an Abelian model is not expected to contain any coherence effects between gluons, so that one should normally use MSTJ(42) = 1 and MSTJ(46) = 0 or 1. Also, $\alpha_{\mathrm{s}}$ is expected to increase with increasing $Q^2$ scale, rather than decrease. No such $\alpha_{\mathrm{s}}$ option is available; the one that comes closest is MSTJ(44) = 0, i.e. a fix value.

MSTJ(50) :

(D = 3) possibility to introduce colour coherence effects in the first branching of a PYSHOW final-state shower. Only relevant when colour flows through from the initial to the final state, i.e. mainly for QCD parton-parton scattering processes.

= 0 :

none.

= 1 :

impose an azimuthal anisotropy. Does not apply when the intermediate state is a resonance, e.g., in a $\t\to \b\mathrm{W}^+$ decay the radiation off the $b$ quark is not restricted.

= 2 :

restrict the polar angle of a branching to be smaller than the scattering angle of the relevant colour flow. Does not apply when the intermediate state is a resonance.

= 3 :

both azimuthal anisotropy and restricted polar angles. Does not apply when the intermediate state is a resonance.

= 4 - 6 :

as = 1 - 3, except that now also decay products of coloured resonances are restricted in angle.

Note:

for subsequent branchings the (polar) angular ordering is automatic (MSTP(42) = 2) and MSTJ(46) = 3).

PARJ(80) :

(D = 0.5) `parity' mixing parameter, $\alpha$ value for the PYMAEL routine, to be used when MSTJ(38) is nonvanishing.

PARJ(81) :

(D = 0.29 GeV) $\Lambda$ value in running $\alpha_{\mathrm{s}}$ for parton showers (see MSTJ(44)). This is used in all user calls to PYSHOW, in the PYEEVT/PYONIA $\mathrm{e}^+\mathrm{e}^-$ routines, and in a resonance decay. It is not intended for other time-like showers, however, for which PARP(72) is used. This parameter ought to be reduced by about a factor of two for use with the PYPTFS routine.

PARJ(82) :

(D = 1.0 GeV) invariant mass cut-off $m_{\mathrm{min}}$ of PYSHOW parton showers, below which partons are not assumed to radiate. For $Q^2 = p_{\perp}^2$ (MSTJ(44) = 2) PARJ(82)/2 additionally gives the minimum $p_{\perp}$ of a branching. To avoid infinite $\alpha_{\mathrm{s}}$ values, one must have PARJ(82)$> 2 \times$PARJ(81) for MSTJ(44) $\geq 1$ (this is automatically checked in the program, with $2.2 \times$PARJ(81) as the lowest value attainable). When the PYPTFS routine is called, it is twice the $p_{\perp\mathrm{min}}$ cut.

PARJ(83) :

(D = 1.0 GeV) invariant mass cut-off $m_{\mathrm{min}}$ used for photon emission in PYSHOW parton showers, below which quarks are not assumed to radiate. The function of PARJ(83) closely parallels that of PARJ(82) for QCD branchings, but there is a priori no requirement that the two be equal. The cut-off for photon emission off leptons is given by PARJ(90). When the PYPTFS routine is called, it is twice the $p_{\perp\mathrm{min}}$ cut.

PARJ(84) :

(D = 1.) used for option MSTJ(41) = 10 as a multiplicative factor in the prompt photon emission rate in final-state parton showers. Unphysical but useful technical trick, so beware!

PARJ(85), PARJ(86) :

(D = 10., 10.) maximum opening angles allowed in the first branching of parton showers; see MSTJ(48).

PARJ(87) :

(D = 0.) coupling of $\mathrm{g}\to \mathrm{g}\mathrm{g}$ in scalar gluon shower, see MSTJ(49) = 1.

PARJ(88) :

(D = 0.) coupling of $\mathrm{g}\to \mathrm{q}\overline{\mathrm{q}}$ in scalar gluon shower (per quark species), see MSTJ(49) = 1.

PARJ(89) :

(D = 0. GeV) the width of the unstable particle studied for the MSTJ(40) > 0 options; to be set by you (separately for each PYSHOW call, if need be).

PARJ(90) :

(D = 0.0001 GeV) invariant mass cut-off $m_{\mathrm{min}}$ used for photon emission in PYSHOW parton showers, below which leptons are not assumed to radiate, cf. PARJ(83) for radiation off quarks. When the PYPTFS routine is called, it is twice the $p_{\perp\mathrm{min}}$ cut. By making this separation of cut-off values, photon emission off leptons becomes more realistic, covering a larger part of the phase space. The emission rate is still not well reproduced for lepton-photon invariant masses smaller than roughly twice the lepton mass itself.

Purpose:

to give access to status code and parameters which regulate the performance of PYTHIA. Most parameters are described in section ; here only those related to PYSSPA/PYPTIS and PYSHOW/PYPTFS are described.

MSTP(22) :

(D = 0) special override of normal $Q^2$ definition used for maximum of parton-shower evolution. This option only affects processes 10 and 83 (Deeply Inelastic Scattering) and only in lepton-hadron events.

= 0 :

use the scale as given in MSTP(32).

= 1 :

use the DIS $Q^2$ scale, i.e. $-\hat{t}$.

= 2 :

use the DIS $W^2$ scale, i.e. $(-\hat{t})(1-x)/x$.

= 3 :

use the DIS $Q \times W$ scale, i.e. $(-\hat{t}) \sqrt{(1-x)/x}$.

= 4 :

use the scale $Q^2 (1-x) \max(1, \ln(1/x))$, as motivated by first-order matrix elements [Ing80,Alt78].

Note:

in all of these alternatives, a multiplicative factor is introduced by PARP(67) and PARP(71), as usual.

MSTP(61) :

(D = 2) master switch for initial-state QCD and QED radiation.

= 0 :

off.

= 1 :

on for QCD radiation in hadronic events and QED radiation in leptonic ones. (Not implemented for PYPTIS, equivalent to 2.).

= 2 :

on for QCD and QED radiation in hadronic events and QED radiation in leptonic ones.

MSTP(62) :

(D = 3) level of coherence imposed on the space-like parton-shower evolution.

= 1 :

none, i.e. neither $Q^2$ values nor angles need be ordered in PYSSPA, while $p_{\perp}^2$ values are ordered in PYPTIS.

= 2 :

$Q^2$ values in PYSSPA and $p_{\perp}^2$ values in PYPTIS are strictly ordered, increasing towards the hard interaction.

= 3 :

$Q^2$/$p_{\perp}^2$ values and opening angles of emitted (on-mass-shell or time-like) partons are both strictly ordered, increasing towards the hard interaction.

MSTP(63) :

(D = 2) structure of associated time-like showers, i.e. showers initiated by emission off the incoming space-like partons in PYSSPA.

= 0 :

no associated showers are allowed, i.e. emitted partons are put on the mass shell.

= 1 :

a shower may evolve, with maximum allowed time-like virtuality set by the phase space only.

= 2 :

a shower may evolve, with maximum allowed time-like virtuality set by phase space or by PARP(71) times the $Q^2$ value of the space-like parton created in the same vertex, whichever is the stronger constraint.

= 3 :

a shower may evolve, with maximum allowed time-like virtuality set by phase space, but further constrained to evolve within a cone with opening angle (approximately) set by the opening angle of the branching where the showering parton was produced.

MSTP(64) :

(D = 2) choice of $\alpha_{\mathrm{s}}$ and $Q^2$ scale in space-like parton showers in PYSSPA.

= 0 :

$\alpha_{\mathrm{s}}$ is taken to be fix at the value PARU(111).

= 1 :

first-order running $\alpha_{\mathrm{s}}$ with argument PARP(63)$Q^2$.

= 2 :

first-order running $\alpha_{\mathrm{s}}$ with argument PARP(64)$k_{\perp}^2 =$PARP(64)$(1-z)Q^2$.

MSTP(65) :

(D = 1) treatment of soft-gluon emission in space-like parton-shower evolution in PYSSPA.

= 0 :

soft gluons are entirely neglected.

= 1 :

soft-gluon emission is resummed and included together with the hard radiation as an effective $z$ shift.

MSTP(66) :

(D = 5) choice of lower cut-off for initial-state QCD radiation in VMD or anomalous photoproduction events, and matching to primordial $k_{\perp}$.

= 0 :

the lower $Q^2$ cutoff is the standard one in PARP(62)$^2$.

= 1 :

for anomalous photons, the lower $Q^2$ cut-off is the larger of PARP(62)$^2$ and VINT(283) or VINT(284), where the latter is the virtuality scale for the $\gamma \to \mathrm{q}\overline{\mathrm{q}}$ vertex on the appropriate side of the event. The VINT values are selected logarithmically even between PARP(15)$^2$ and the $Q^2$ scale of the parton distributions of the hard process.

= 2 :

extended option of the above, intended for virtual photons. For VMD photons, the lower $Q^2$ cut-off is the larger of PARP(62)$^2$ and the $P^2_{\mathrm{int}}$ scale of the SaS parton distributions. For anomalous photons, the lower cut-off is chosen as for = 1, but the VINT(283) and VINT(284) are here selected logarithmically even between $P^2_{\mathrm{int}}$ and the $Q^2$ scale of the parton distributions of the hard process.

= 3 :

the $k_{\perp}$ of the anomalous/GVMD component is distributed like $1/k_{\perp}^2$ between $k_0$ and $p_{\perp\mathrm{min}}(W^2)$. Apart from the change of the upper limit, this option works just like = 1.

= 4 :

a stronger damping at large $k_{\perp}$, like $\d k_{\perp}^2/(k_{\perp}^2 + Q^2/4)^2$ with $k_0 < k_{\perp}< p_{\perp\mathrm{min}}(W^2)$. Apart from this, it works like = 1.

= 5 :

a $k_{\perp}$ generated as in = 4 is added vectorially with a standard Gaussian $k_{\perp}$ generated like for VMD states. Ensures that GVMD has typical $k_{\perp}$'s above those of VMD, in spite of the large primordial $k_{\perp}$'s implied by hadronic physics. (Probably attributable to a lack of soft QCD radiation in parton showers.)

MSTP(67) :

(D = 2) possibility to introduce colour coherence effects in the first branching of the backwards evolution of an initial-state shower in PYSSPA; mainly of relevance for QCD parton-parton scattering processes.

= 0 :

none.

= 2 :

restrict the polar angle of a branching to be smaller than the scattering angle of the relevant colour flow.

Note 1:

azimuthal anisotropies have not yet been included.

Note 2:

for subsequent branchings, MSTP(62) = 3 is used to restrict the (polar) angular range of branchings.

MSTP(68) :

(D = 3) choice of maximum virtuality scale and matrix-element matching scheme for initial-state radiation. To this end, the basic scattering processes are classified as belonging to one or several of the following categories (hard-coded for each process):

ISQCD = 1 :

QCD processes, i.e. processes for which the hard scattering scale should normally set the limit for subsequent multiple interactions. Consists of processes 11, 12, 13, 28, 53 and 68.

ISQCD = 0 :

Other processes. Multiple interactions normally allowed to populate full phase space.

ISJETS = 1 :

Processes of the $X+$jet type, i.e. processes for which the matrix element already contains one radiated jet. For such processes, as well as for QCD processes, the scale of the already existing jet(s) should set the limit for further parton-shower evolution.

ISJETS = 0 :

Processes which do not contain parton-shower jets at leading order.

ISMECR = 1 :

Processes for which matrix element merging to the $X$+jet rate have been implemented. This list contains the processes 1, 2, 141, 142, 144, 102, 152 and 157, i.e. single $s$-channel colourless gauge boson and Higgs production: $\gamma^* / \mathrm{Z}^0$, $\mathrm{W}^{\pm}$, ${\mathrm{Z}'}^0$, ${\mathrm{W}'}^{\pm}$, $\mathrm{R}$, $\mathrm{h}^0$, $\H ^0$ and $\H ^{\pm}$. Here the maximum scale of shower evolution is $s$, the total squared energy. The nearest branching on either side of the hard scattering is corrected by the ratio of the first-order matrix-element weight to the parton-shower one, so as to obtain an improved description. For gauge boson production, this branching can be of the types $\mathrm{q}\to \mathrm{q}+ \mathrm{g}$, $\mathrm{f}\to \mathrm{f}+ \gamma$, $\mathrm{g}\to \mathrm{q}+ \overline{\mathrm{q}}$ or $\gamma \to \mathrm{f}+ \overline{\mathrm{f}}$, while for Higgs production it is $\mathrm{g}\to \mathrm{g}+ \mathrm{g}$. See section for a detailed description. Note that the improvements apply both for incoming hadron and lepton beams.

ISMECR = 0 :

Processes for which no such corrections are implemented.

Given this information, the following options are available:

= 0 :

maximum shower virtuality is the same as the $Q^2$ choice for the parton distributions, see MSTP(32). (Except that the multiplicative extra factor PARP(34) is absent and instead PARP(67) can be used for this purpose.) No matrix-element correction.

= 1 :

as = 0 for most processes, but for processes of the ISMECR = 1 type the maximum evolution scale is the full CM energy, and ME corrections are applied where available.

= 2 :

as = 0 for most processes, but for processes of the ISQCD = 0 and ISJETS = 0 types the maximum evolution scale is the full CM energy. No ME corrections are applied.

= 3 :

as = 2, but ME corrections are applied where available.

= -1 :

as = 0, except that there is no requirement on $\hat{u}$ being negative. (Only applies to the old PYSSPA shower.)

MSTP(69) :

(D = 0) possibility to change $Q^2$ scale for parton distributions from the MSTP(32) choice, especially for $\mathrm{e}^+\mathrm{e}^-$.

= 0 :

use MSTP(32) scale.

= 1 :

in lepton-lepton collisions, the QED lepton-inside-lepton parton distributions are evaluated with $s$, the full squared c.m. energy, as scale.

= 2 :

$s$ is used as parton distribution scale also in other processes.

MSTP(70) :

(D = 1) regularization scheme for ISR radiation when $p_{\perp}\to 0$ in the new $p_{\perp}$-ordered evolution in PYPTIS.

= 0 :

sharp cut-off at $p_{\perp\mathrm{min}}=$PARP(62)$/2$.

= 1 :

sharp cut-off at $p_{\perp\mathrm{min}}=$PARP(81), rescaled with energy, the same as the $p_{\perp\mathrm{min}}$ scale used for multiple interactions when MSTP(82) = 1.

= 2 :

a smooth turnoff at $p_{\perp 0}=$PARP(82), rescaled with energy, the same as the $p_{\perp 0}$ scale used for multiple interactions when MSTP(82) > 1. Thus $\d p_{\perp}^2/p_{\perp}^2 \to \d p_{\perp}^2/(p_{\perp}^2 + p_{\perp 0}^2)$ and $\alpha_{\mathrm{s}}(p_{\perp}^2) \to \alpha_{\mathrm{s}}(p_{\perp}^2 + p_{\perp 0}^2)$. Note that, even though one could in principle allow branching down to vanishing $p_{\perp}$ this way (with a highly suppressed rate), the algorithm is nonetheless forced to stop once the evolution has reached a scale equal to 1.1 times the 3-flavour $\Lambda_{\mathrm{QCD}}$.

MSTP(71) :

(D = 1) master switch for final-state QCD and QED radiation.

= 0 :

off.

= 1 :

on.

MSTP(72) :

(D = 1) maximum scale for radiation off FSR dipoles stretched between ISR partons in the new $p_{\perp}$-ordered evolution in PYPTIS.

= 0 :

the $p_{\perp\mathrm{max}}$ scale of FSR is set as the minimum of the $p_{\perp}$ production scale of the two endpoint partons. Dipoles stretched to remnants do not radiate.

= 1 :

the $p_{\perp\mathrm{max}}$ scale of FSR is set as the $p_{\perp}$ production scale of the respective radiating parton. Dipoles stretched to remnants do not radiate.

= 2 :

the $p_{\perp\mathrm{max}}$ scale of FSR is set as the $p_{\perp}$ production scale of the respective radiating parton. Dipoles stretched to remnants can radiate (by emissions off the perturbative-parton side, not the remnant one).

PARP(61) :

(D = 0.25 GeV) $\Lambda$ value used in space-like parton shower (see MSTP(64)). This value may be overwritten, see MSTP(3).

PARP(62) :

(D = 1. GeV) effective cut-off $Q$ or $k_{\perp}$ value (see MSTP(64)), below which space-like parton showers are not evolved. Primarily intended for QCD showers in incoming hadrons, but also applied to $\mathrm{q}\to \mathrm{q}\gamma$ branchings.

PARP(63) :

(D = 0.25) in space-like shower evolution the virtuality $Q^2$ of a parton is multiplied by PARP(63) for use as a scale in $\alpha_{\mathrm{s}}$ and parton distributions when MSTP(64) = 1.

PARP(64) :

(D = 1.) in space-like parton-shower evolution the squared transverse momentum evolution scale $k_{\perp}^2$ is multiplied by PARP(64) for use as a scale in $\alpha_{\mathrm{s}}$ and parton distributions when MSTP(64) = 2.

PARP(65) :

(D = 2. GeV) effective minimum energy (in c.m. frame) of time-like or on-shell parton emitted in space-like shower; see also PARP(66). For a hard subprocess moving in the rest frame of the hard process, this number is reduced roughly by a factor $1/\gamma$ for the boost to the hard-scattering rest frame.

PARP(66) :

(D = 0.001) effective lower cut-off on $1-z$ in space-like showers, in addition to the cut implied by PARP(65).

PARP(67) :

(D = 4.) the $Q^2$ scale of the hard scattering (see MSTP(32)) is multiplied by PARP(67) to define the maximum parton virtuality allowed in $Q^2$-ordered space-like showers. This does not apply to $s$-channel resonances, where the m aximum virtuality is set by $m^2$. It does apply to all user-defined processes,however. The current default is based on Tevatron studies (see e.g. [Fie02]), while arguments from a matching of scales in heavy-flavour production [Nor98] might suggest unity. The range 1-4 should be considered free for variations.

PARP(68) :

(D = 0.001 GeV) lower $Q$ cut-off for QED space-like showers. Comes in addition to a hardcoded cut that the $Q^2$ is at least $2m_{\mathrm{e}}^2$, $2m_{\mu}^2$ or $2m_{\tau}^2$, as the case may be.

PARP(71) :

(D = 4.) the $Q^2$ scale of the hard scattering (see MSTP(32)) is multiplied by PARP(71) to define the maximum parton virtuality allowed in time-like showers. This does not apply to $s$-channel resonances, where the maximum virtuality is set by $m^2$. Like for PARP(67) this number is uncertain.

PARP(72) :

(D = 0.25 GeV) $\Lambda$ value used in running $\alpha_{\mathrm{s}}$ for time-like parton showers, except for showers in the decay of a resonance. (Resonance decay, e.g. $\gamma^*/Z^0$ decay, is instead set by PARJ(81).)

Purpose:

to keep track of partons that can radiate in final-state showers.

NPART :

the number of partons that may radiate, determining how much of IPART and PTPART is currently in use.

NPARTD :

dummy, to avoid some compiler warnings.

IPART :

the line number in /PYJETS/ in which a radiating parton is stored.

PTPART :

the $p_{\perp}$ scale of the parton, from which it is to be evolved downwards in search of a first branching.