Definition of Initial Configuration or Variables

With the use of the conventions described for the event record, it is possible to specify any initial jet/particle configuration. This task is simplified for a number of often occurring situations by the existence of the filling routines below. It should be noted that many users do not come in direct contact with these routines, since that is taken care of by higher-level routines for specific processes, particularly PYEVNT and PYEEVT.

Several calls to the routines can be combined in the specification. In case one call is enough, the complete fragmentation/decay chain may be simulated at the same time. At each call, the value of N is updated to the last line used for information in the call, so if several calls are used, they should be made with increasing IP number, or else N should be redefined by hand afterwards.

The routine PYJOIN is very useful to define the colour flow in more complicated parton configurations; thereby one can bypass the not so trivial rules for how to set the K(I,4) and K(I,5) colour-flow information.

The routine PYGIVE contains a facility to set various commonblock variables in a controlled and documented fashion.

Purpose:

to add one entry to the event record, i.e. either a parton or a particle.

IP :

normally line number for the parton/particle. There are two exceptions.
If IP=0, line number 1 is used and PYEXEC is called.
If IP<0, line -IP is used, with status code K(-IP,2)=2 rather than 1; thus a parton system may be built up by filling all but the last parton of the system with IP<0.

KF :

parton/particle flavour code.

PE :

parton/particle energy. If PE is smaller than the mass, the parton/particle is taken to be at rest.

THE, PHI :

polar and azimuthal angle for the momentum vector of the parton/particle.

Purpose:

to add two entries to the event record, i.e. either a 2-parton system or two separate particles.

IP :

normally line number for the first parton/particle, with the second in line IP+1. There are two exceptions.
If IP=0, lines 1 and 2 are used and PYEXEC is called.
If IP<0, lines -IP and -IP+1 are used, with status code K(I,1)=3, i.e. with special colour connection information, so that a parton shower can be generated by a PYSHOW call, followed by a PYEXEC call, if so desired (only relevant for partons).

KF1, KF2 :

flavour codes for the two partons/particles.

PECM :

( $=E_{\mathrm{cm}}$) the total energy of the system.

Remark:

the system is given in the c.m. frame, with the first parton/particle going out in the $+z$ direction.

Purpose:

to add three entries to the event record, i.e. either a 3-parton system or three separate particles.

IP :

normally line number for the first parton/particle, with the other two in IP+1 and IP+2. There are two exceptions.
If IP=0, lines 1, 2 and 3 are used and PYEXEC is called.
If IP<0, lines -IP through -IP+2 are used, with status code K(I,1)=3, i.e. with special colour connection information, so that a parton shower can be generated by a PYSHOW call, followed by a PYEXEC call, if so desired (only relevant for partons).

KF1, KF2, KF3:

flavour codes for the three partons/particles.

PECM :

( $E_{\mathrm{cm}}$) the total energy of the system.

X1, X3 :

$x_i = 2 E_i / E_{\mathrm{cm}}$, i.e. twice the energy fraction taken by the $i$'th parton. Thus $x_2 = 2 - x_1 - x_3$, and need not be given. Note that not all combinations of $x_i$ are inside the physically allowed region.

Remarks :

the system is given in the c.m. frame, in the $xz$-plane, with the first parton going out in the $+z$ direction and the third one having $p_x > 0$. A system must be given in the order of colour flow, so $\mathrm{q}\mathrm{g}\overline{\mathrm{q}}$ and $\overline{\mathrm{q}}\mathrm{g}\mathrm{q}$ are allowed but $\mathrm{q}\overline{\mathrm{q}}\mathrm{g}$ not. Thus $x1$ and $x_3$ come to correspond to what is normally called $x_1$ and $x_2$, i.e. the scaled $\mathrm{q}$ and $\overline{\mathrm{q}}$ energies.

Purpose:

to add four entries to the event record, i.e. either a 4-parton system or four separate particles (or, for $\mathrm{q}\overline{\mathrm{q}}\mathrm{q}' \overline{\mathrm{q}}'$ events, two 2-parton systems).

IP :

normally line number for the first parton/particle, with the other three in lines IP+1, IP+2 and IP+3. There are two exceptions.
If IP=0, lines 1, 2, 3 and 4 are used and PYEXEC is called.
If IP<0, lines -IP through -IP+3 are used, with status code K(I,1)=3, i.e. with special colour connection information, so that a parton shower can be generated by a PYSHOW call, followed by a PYEXEC call, if so desired (only relevant for partons).

KF1,KF2,KF3,KF4 :

flavour codes for the four partons/particles.

PECM :

( $=E_{\mathrm{cm}}$) the total energy of the system.

X1,X2,X4 :

$x_i = 2 E_i / E_{\mathrm{cm}}$, i.e. twice the energy fraction taken by the $i$'th parton. Thus $x_3 = 2 - x_1 - x_2 - x_4$, and need not be given.

X12,X14 :

$x_{ij} = 2 p_i p_j/E_{\mathrm{cm}}^2$, i.e. twice the four-vector product of the momenta for partons $i$ and $j$, properly normalized. With the masses known, other $x_{ij}$ may be constructed from the $x_i$ and $x_{ij}$ given. Note that not all combinations of $x_i$ and $x_{ij}$ are inside the physically allowed region.

Remarks:

the system is given in the c.m. frame, with the first parton going out in the $+z$ direction and the fourth parton lying in the $xz$-plane with $p_x > 0$. The second parton will have $p_y > 0$ and $p_y < 0$ with equal probability, with the third parton balancing this $p_y$ (this corresponds to a random choice between the two possible stereoisomers). A system must be given in the order of colour flow, e.g. $\mathrm{q}\mathrm{g}\mathrm{g}\overline{\mathrm{q}}$ and $\mathrm{q}\overline{\mathrm{q}}' \mathrm{q}'\overline{\mathrm{q}}$.

Purpose:

to connect a number of previously defined partons into a string configuration. Initially the partons must be given with status codes K(I,1)= 1, 2 or 3. Afterwards the partons all have status code 3, i.e. are given with full colour-flow information. Compared to the normal way of defining a parton system, the partons need therefore not appear in the same sequence in the event record as they are assumed to do along the string. It is also possible to call PYSHOW for all or some of the entries making up the string formed by PYJOIN.

NJOIN:

the number of entries that are to be joined by one string.

IJOIN:

an one-dimensional array, of size at least NJOIN. The NJOIN first numbers are the positions of the partons that are to be joined, given in the order the partons are assumed to appear along the string. If the system consists entirely of gluons, the string is closed by connecting back the last to the first entry.

Remarks:

only one string (i.e. one colour singlet) may be defined per call, but one is at liberty to use any number of PYJOIN calls for a given event. The program will check that the parton configuration specified makes sense, and not take any action unless it does. Note, however, that an initially sensible parton configuration may become nonsensical, if only some of the partons are reconnected, while the others are left unchanged.

Purpose:

to set the value of any variable residing in the commmonblocks PYJETS, PYDAT1, PYDAT2, PYDAT3, PYDAT4, PYDATR, PYSUBS, PYPARS, PYINT1, PYINT2, PYINT3, PYINT4, PYINT5, PYINT6, PYINT7, PYINT8, PYMSSM or PYMSRV. This is done in a more controlled fashion than by directly including the common blocks in your program, in that array bounds are checked and the old and new values for the variable changed are written to the output for reference. An example how PYGIVE can be used to parse input from a file is given in subsection .

CHIN :

character expression of length at most 100 characters, with requests for variables to be changed, stored in the form
variable1=value1;variable2=value2;variable3=value3... .
Note that an arbitrary number of instructions can be stored in one call if separated by semicolons, and that blanks may be included anyplace. An exclamation mark is recognized as the beginning of a comment, which is not to be processed. Normal parsing is resumed at the next semicolon (if any remain). An example would be
CALL PYGIVE('MSEL=16!Higgs production;PMAS(25,1)=115.!h0 mass')
The variable$_i$ may be any single variable in the PYTHIA common blocks, and the value$_i$ must be of the correct integer, real or character (without extra quotes) type. Array indices and values must be given explicitly, i.e. cannot be variables in their own right. The exception is that the first index can be preceded by a C, signifying that the index should be translated from normal KF to compressed KC code with a PYCOMP call; this is allowed for the KCHG, PMAS, MDCY, CHAF and MWID arrays.
If a value$_i$ is omitted, i.e. with the construction variable=, the current value is written to the output, but the variable itself is not changed.
The writing of info can be switched off by MSTU(13)=0.

Remark :

The checks on array bounds are hardwired into this routine. Therefore, if you change array dimensions and MSTU(3), MSTU(6) and/or MSTU(7), as allowed by other considerations, these changes will not be known to PYGIVE. Normally this should not be a problem, however.