Run information

When PYINIT is called in the main program, with 'USER' as first argument (which makes the other arguments dummy), it signals that external processes are to be implemented. Then PYINIT, as part of its initialization tasks, will call the routine UPINIT.

Purpose:

routine to be provided by you when you want to implement external processes, wherein the contents of the HEPRUP common block are set. This information specifies the character of the run, both beams and processes, see further below.

Note 1:

alternatively, the HEPRUP common block could be filled already before PYINIT is called, in which case UPINIT could be empty. We recommend UPINIT as the logical place to collect the relevant information, however.

Note 2:

a dummy copy of UPINIT is distributed with the program, in order to avoid potential problems with unresolved external references. This dummy should not be linked when you supply your own UPINIT routine.

Purpose:

to contain the initial information necessary for the subsequent generation of complete events from externally provided parton configurations. The IDBMUP, EBMUP, PDFGUP and PDFSUP variables specify the nature of the two incoming beams. IDWTUP is a master switch, selecting the strategy to be used to mix different processes. NPRUP gives the number of different external processes to mix, and XSECUP, XERRUP, XMAXUP and LPRUP information on each of these. The contents in this common block must remain unchanged by the user during the course of the run, once set in the initialization stage.
This common block should be filled in the UPINIT routine or, alternatively, before the PYINIT call. During the run, PYTHIA may update the XMAXUP values as required.

MAXPUP :

the maximum number of distinguishable processes that can be defined. (Each process in itself could consist of several subprocesses that have been distinguished in the parton-level generator, but where this distinction is not carried along.)

IDBMUP :

the PDG codes of the two incoming beam particles (or, in alternative terminology, the beam and target particles).
In PYTHIA, this replaces the information normally provided by the BEAM and TARGET arguments of the PYINIT call. Only particles which are acceptable BEAM or TARGET arguments may also be used in IDBMUP. The 'gamma/lepton' options are not available.

EBMUP :

the energies, in GeV, of the two incoming beam particles. The first (second) particle is taken to travel in the $+z$ ($-z$) direction.
The standard also allows non-collinear and varying-energy beams to be specified, see ISTUP = -9 below, but this is not yet implemented in PYTHIA.

PDFGUP, PDFSUP :

the author group (PDFGUP) and set (PDFSUP) of the parton distributions of the two incoming beams, as used in the generation of the parton-level events. Numbers are based on the PDFLIB [Plo93] lists. This enumeration may not always be up to date, but it provides the only unique integer labels for parton distributions that we have. Where no codes are yet assigned to the parton distribution sets used, one should do as best as one can, and be prepared for more extensive user interventions to interpret the information. For lepton beams, or when the information is not provided for other reasons, one should put PDFGUP = PDFSUP = -1.
By knowing which set has been used, it is possible to reweight cross sections event by event, to correspond to another set.
Note that PYTHIA does not access the PDFGUP or PDFSUP values in its description of internal processes or initial-state showers. If you want this to happen, you have to manipulate the MSTP(51) - MSTP(56) switches. For instance, to access PDFLIB for protons, put MSTP(51) = 1000*PDFGUP + PDFSUP and MSTP(52) = 2 in UPINIT. (And remove the dummy PDFLIB routines, as described for MSTP(52).) Also note that PDFGUP and PDFSUP allow an independent choice of parton distributions on the two sides of the event, whereas PYTHIA only allows one single choice for all protons, another for all pions and a third for all photons.

IDWTUP :

master switch dictating how event weights and cross sections should be interpreted. Several different models are presented in detail below. There will be tradeoffs between these, e.g. a larger flexibility to mix and re-mix several different processes could require a larger administrative machinery. Therefore the best strategy would vary, depending on the format of the input provided and the output desired. In some cases, parton-level configurations have already been generated with one specific model in mind, and then there may be no choice.
IDWTUP significantly affects the interpretation of XWGTUP, XMAXUP and XSECUP, as described below, but the basic nomenclature is the following. XWGTUP is the event weight for the current parton-level event, stored in the HEPEUP common block. For each allowed external process i, XMAXUP(i) gives the maximum event weight that could be encountered, while XSECUP(i) is the cross section of the process. Here i is an integer in the range between 1 and NPRUP; see the LPRUP description below for comments on alternative process labels.

= 1 :

parton-level events come with a weight when input to PYTHIA, but are then accepted or rejected, so that fully generated events at output have a common weight, customarily defined as $+1$. The event weight XWGTUP is a non-negative dimensional quantity, in pb (converted to mb in PYTHIA), with a mean value converging to the total cross section of the respective process. For each process i, the XMAXUP(i) value provides an upper estimate of how large XWGTUP numbers can be encountered. There is no need to supply an XSECUP(i) value; the cross sections printed with PYSTAT(1) are based entirely on the averages of the XWGTUP numbers (with a small correction for the fraction of events that PYEVNT fails to generate in full for some reason).
The strategy is that PYEVNT selects which process i should be generated next, based on the relative size of the XMAXUP(i) values. The UPEVNT routine has to fill the HEPEUP common block with a parton-level event of the requested type, and give its XWGTUP event weight. The event is accepted by PYEVNT with probability XWGTUP/XMAXUP(i). In case of rejection, PYEVNT selects a new process i and asks for a new event. This ensures that processes are mixed in proportion to their average XWGTUP values.
This model presumes that UPEVNT is able to return a parton-level event of the process type requested by PYEVNT. It works well if each process is associated with an input stream of its own, either a subroutine generating events `on the fly' or a file of already generated events. It works less well if parton-level events from different processes already are mixed in a single file, and therefore cannot easily be returned in the order wanted by PYEVNT. In the latter case one should either use another model or else consider reducing the level of ambition: even if you have mixed several different subprocesses on a file, maybe there is no need for PYTHIA to know this finer classification, in which case we may get back to a situation with one `process' per external file. Thus the subdivision into processes should be a matter of convenience, not a straight jacket. Specifically, the shower and hadronization treatment of a parton-level event is independent of the process label assigned to it.
If the events of some process are already available unweighted, then a correct mixing of this process with others is ensured by putting XWGTUP = XMAXUP(i), where both of these numbers now is the total cross section of the process.
Each XMAXUP(i) value must be known from the very beginning, e.g. from an earlier exploratory run. If a larger value is encountered during the course of the run, a warning message will be issued and the XMAXUP(i) value (and its copy in XSEC(ISUB,1)) increased. Events generated before this time will have been incorrectly distributed, both in the process composition and in the phase space of the affected process, so that a bad estimate of XMAXUP(i) may require a new run with a better starting value.
The model described here agrees with the one used for internal PYTHIA processes, and these can therefore freely be mixed with the external ones. Internal processes are switched on with MSUB(ISUB) = 1, as usual, either before the PYINIT call or in the UPINIT routine. One cannot use MSEL to select a predefined set of processes, for technical reasons, wherefore MSEL = 0 is hardcoded when external processes are included.
A reweighting of events is feasible, e.g. by including a kinematics-dependent $K$ factor into XWGTUP, so long as XMAXUP(i) is also properly modified to take this into account. Optionally it is also possible to produce events with non-unit weight, making use the PYEVWT facility, see subsection . This works exactly the same way as for internal PYTHIA processes, except that the event information available inside PYEVWT would be different for external processes. You may therefore wish to access the HEPEUP common block inside your own copy of PYEVWT, where you calculate the event weight.
In summary, this option provides maximal flexibility, but at the price of potentially requiring the administration of several separate input streams of parton-level events.

= -1 :

same as = 1 above, except that event weights may be either positive or negative on input, and therefore can come with an output weight of $+1$ or $-1$. This weight is uniquely defined by the sign of XWGTUP. It is also stored in PARI(7). The need for negative-weight events arises in some next-to-leading-order calculations, but there are inherent dangers, discussed in subsection below.
In order to allow a correct mixing between processes, a process of indeterminate cross section sign has to be split up in two, where one always gives a positive or vanishing XWGTUP, and the other always gives it negative or vanishing. The XMAXUP(i) value for the latter process should give the negative XWGTUP of largest magnitude that will be encountered. PYEVNT selects which process i that should be generated next, based on the relative size of the |XMAXUP(i)| values. A given event is accepted with probability |XWGTUP|/|XMAXUP(i)|.

= 2 :

parton-level events come with a weight when input to PYTHIA, but are then accepted or rejected, so that events at output have a common weight, customarily defined as $+1$. The non-negative event weight XWGTUP and its maximum value XMAXUP(i) may or may not be dimensional quantities; it does not matter since only the ratio XWGTUP/XMAXUP(i) will be used. Instead XSECUP(i) contains the process cross section in pb (converted to mb in PYTHIA). It is this cross section that appears in the PYSTAT(1) table, only modified by the small fraction of events that PYEVNT fails to generate in full for some reason.
The strategy is that PYEVNT selects which process i should be generated next, based on the relative size of the XSECUP(i) values. The UPEVNT routine has to fill the HEPEUP common block with a parton-level event of the requested type, and give its XWGTUP event weight. The event is accepted by PYEVNT with probability XWGTUP/XMAXUP(i). In case of rejection, the process number i is retained and PYEVNT asks for a new event of this kind. This ensures that processes are mixed in proportion to their XSECUP(i) values.
This model presumes that UPEVNT is able to return a parton-level event of the process type requested by PYEVNT, with comments exactly as for the = 1 option.
If the events of some process are already available unweighted, then a correct mixing of this process with others is ensured by putting XWGTUP = XMAXUP(i).
Each XMAXUP(i) and XSECUP(i) value must be known from the very beginning, e.g. from an earlier integration run. If a larger value is encountered during the course of the run, a warning message will be issued and the XMAXUP(i) value increased. This will not affect the process composition, but events generated before this time will have been incorrectly distributed in the phase space of the affected process, so that a bad estimate of XMAXUP(i) may require a new run with a better starting value.
While the generation model is different from the normal internal PYTHIA one, it is sufficiently close that internal processes can be freely mixed with the external ones, exactly as described for the = 1 option. In such a mix, internal processes are selected according to their equivalents of XMAXUP(i) and at rejection a new i is selected, whereas external ones are selected according to XSECUP(i) with i retained when an event is rejected.
A reweighting of individual events is no longer simple, since this would change the XSECUP(i) value nontrivially. Thus a new integration run with the modified event weights would be necessary to obtain new XSECUP(i) and XMAXUP(i) values. An overall rescaling of each process separately can be obtained by modifying the XSECUP(i) values accordingly, however, e.g. by a relevant $K$ factor.
In summary, this option is similar to the = 1 one. The input of XSECUP(i) allows good cross section knowledge also in short test runs, but at the price of a reduced flexibility to reweight events.

= -2 :

same as = 2 above, except that event weights may be either positive or negative on input, and therefore can come with an output weight of $+1$ or $-1$. This weight is uniquely defined by the sign of XWGTUP. It is also stored in PARI(7). The need for negative-weight events arises in some next-to-leading-order calculations, but there are inherent dangers, discussed in subsection below.
In order to allow a correct mixing between processes, a process of indeterminate cross section sign has to be split up in two, where one always gives a positive or vanishing XWGTUP, and the other always gives it negative or vanishing. The XMAXUP(i) value for the latter process should give the negative XWGTUP of largest magnitude that will be encountered, and XSECUP(i) should give the integrated negative cross section. PYEVNT selects which process i that should be generated next, based on the relative size of the |XSECUP(i)| values. A given event is accepted with probability |XWGTUP|/|XMAXUP(i)|.

= 3 :

parton-level events come with unit weight when input to PYTHIA, XWGTUP = 1, and are thus always accepted. This makes the XMAXUP(i) superfluous, while XSECUP(i) should give the cross section of each process.
The strategy is that that the next process type i is selected by the user inside UPEVNT, at the same time as the HEPEUP common block is filled with information about the parton-level event. This event is then unconditionally accepted by PYEVNT, except for the small fraction of events that PYEVNT fails to generate in full for some reason.
This model allows UPEVNT to read events from a file where different processes already appear mixed. Alternatively, you are free to devise and implement your own mixing strategy inside UPEVNT, e.g. to mimic the ones already outlined for PYEVNT in = 1 and = 2 above.
The XSECUP(i) values should be known from the beginning, in order for PYSTAT(1) to produce a sensible cross section table. This is the only place where it matters, however. That is, the processing of events inside PYTHIA is independent of this information.
In this model it is not possible to mix with internal PYTHIA processes, since not enough information is available to perform such a mixing.
A reweighting of events is completely in the hands of the UPEVNT author. In the case that all events are stored in a single file, and all are to be handed on to PYEVNT, only a common $K$ factor applied to all processes would be possible.
In summary, this option puts more power -- and responsibility -- in the hands of the author of the parton-level generator. It is very convenient for the processing of unweighted parton-level events stored in a single file. The price to be paid is a reduced flexibility in the reweighting of events, or in combining processes at will.

= -3 :

same as = 3 above, except that event weights may be either $+1$ or $-1$. This weight is uniquely defined by the sign of XWGTUP. It is also stored in PARI(7). The need for negative-weight events arises in some next-to-leading-order calculations, but there are inherent dangers, discussed in subsection below.
Unlike the = -1 and = -2 options, there is no need to split a process in two, each with a definite XWGTUP sign, since PYEVNT is not responsible for the mixing of processes. It may well be that the parton-level-generator author has enforced such a split, however, to solve a corresponding mixing problem inside UPEVNT. Information on the relative cross section in the negative- and positive-weight regions may also be useful to understand the character and validity of the calculation (large cancellations means trouble!).

= 4 :

parton-level events come with a weight when input to PYTHIA, and this weight is to be retained unchanged at output. The event weight XWGTUP is a non-negative dimensional quantity, in pb (converted to mb in PYTHIA, and as such also stored in PARI(7)), with a mean value converging to the total cross section of the respective process. When histogramming results, one of these event weights would have to be used.
The strategy is exactly the same as = 3 above, except that the event weight is carried along from UPEVNT to the PYEVNT output. Thus again all control is in the hands of the UPEVNT author.
A cross section can be calculated from the average of the XWGTUP values, as in the = 1 option, and is displayed by PYSTAT(1). Here it is of purely informative character, however, and does not influence the generation procedure. Neither XSECUP(i) or XMAXUP(i) needs to be known or supplied.
In this model it is not possible to mix with internal PYTHIA processes, since not enough information is available to perform such a mixing.
A reweighting of events is completely in the hands of the UPEVNT author, and is always simple, also when events appear sequentially stored in a single file.
In summary, this option allows maximum flexibility for the parton-level-generator author, but potentially at the price of spending a significant amount of time processing events of very small weight. Then again, in some cases it may be an advantage to have more events in the tails of a distribution in order to understand those tails better.

= -4 :

same as = 4 above, except that event weights in XWGTUP may be either positive or negative. In particular, the mean value of XWGTUP is converging to the total cross section of the respective process. The need for negative-weight events arises in some next-to-leading-order calculations, but there are inherent dangers, discussed in subsection below.
Unlike the = -1 and = -2 options, there is no need to split a process in two, each with a definite XWGTUP sign, since PYEVNT does not have to mix processes. However, as for option = -3, such a split may offer advantages in understanding the character and validity of the calculation.

NPRUP :

the number of different external processes, with information stored in the first NPRUP entries of the XSECUP, XERRUP, XMAXUP and LPRUP arrays.

XSECUP :

cross section for each external process, in pb. This information is mandatory for IDWTUP = $\pm 2$, helpful for $\pm 3$, and not used for the other options.

XERRUP :

the statistical error on the cross section for each external process, in pb.
PYTHIA will never make use of this information, but if it is available anyway it provides a helpful service to the user of parton-level generators.
Note that, if a small number $n_{\mathrm{acc}}$ of events pass the experimental selection cuts, the statistical error on this cross section is limited by $\delta \sigma / \sigma \approx 1/\sqrt{n_{\mathrm{acc}}}$, irrespectively of the quality of the original integration. Furthermore, at least in hadronic physics, systematic errors from parton distributions and higher orders typically are much larger than the statistical errors.

XMAXUP :

the maximum event weight XWGTUP that is likely to be encountered for each external process. For IDWTUP = $\pm 1$ it has dimensions pb, while the dimensionality need not be specified for $\pm 2$. For the other IDWTUP options it is not used.

LPRUP :

a unique integer identifier of each external process, free to be picked by you for your convenience. This code is used in the IDPRUP identifier of which process occured.
In PYTHIA, an external process is thus identified by three different integers. The first is the PYTHIA process number, ISUB. This number is assigned by PYINIT at the beginning of each run, by scanning the ISET array for unused process numbers, and reclaiming such in the order they are found. The second is the sequence number i, running from 1 through NPRUP, used to find information in the cross section arrays. The third is the LPRUP(i) number, which can be anything that the user wants to have as a unique identifier, e.g. in a larger database of processes. For PYTHIA to handle conversions, the two KFPR numbers of a given process ISUB are overwritten with the second and third numbers above. Thus the first external process will land in ISUB = 4 (currently), and could have LPRUP(1) = 13579. In a PYSTAT(1) call, it would be listed as User process 13579.