The Monte Carlo program is built as a slave system, i.e. you, the user, have to supply the main program. From this the various subroutines are called on to execute specific tasks, after which control is returned to the main program. Some of these tasks may be very trivial, whereas the `high-level' routines by themselves may make a large number of subroutine calls. Many routines are not intended to be called directly by you, but only from higher-level routines such as PYEXEC, PYEEVT, PYINIT, PYEVNT, or PYEVNW.
Basically, this means that there are three ways by which you communicate with the programs. First, by setting common-block variables, you specify the details of how the programs should perform specific tasks, e.g. which subprocesses should be generated, which particle masses should be assumed, which coupling constants used, which fragmentation scenarios, and so on with hundreds of options and parameters. Second, by calling subroutines you tell the programs to generate events according to the rules established above. Normally there are few subroutine arguments, and those are usually related to details of the physical situation, such as what c.m. energy to assume for events. Third, you can either look at the common block PYJETS to extract information on the generated event, or you can call on various functions and subroutines to analyse the event further for you.
It should be noted that, while the physics content is obviously at the centre of attention, the PYTHIA package also contains a very extensive setup of auxiliary service routines. The hope is that this will provide a comfortable working environment, where not only events are generated, but where you also linger on to perform a lot of the subsequent studies. Of course, for detailed studies, it may be necessary to interface the output directly to a detector simulation program.
The general rule is that all routines have names that are six characters long, beginning with PY. Apart from dummy copies of routines from other libraries, there are three exceptions the length rules: PYK, PYP and PYR. The former two functions are strongly coupled to the K and P matrices in the PYJETS common block, while the latter is very frequently used. Also common-block names are six characters long and start with PY. There are three integer functions, PYK, PYCHGE and PYCOMP. In all routines where they are to be used, they have to be declared INTEGER.
An index to (almost) all subprograms and common-block variables is found in Appendix B.
On the issue of initialization, the routines of different origin and functionality behave quite differently. Routines that are intended to be called from many different places, such as showers, fragmentation and decays, require no specific initialization (except for the one implied by the presence of BLOCK DATA PYDATA, see above), i.e. each event and each task stands on its own. Current common-block values are used to perform the tasks in specific ways, and those rules can be changed from one event to the next (or even within the generation of one and the same event) without any penalty. The random-number generator is initialized at the first call, but usually this is transparent.
In the core process generation machinery (e.g. selection of the hard process kinematics), on the other hand, a sizable amount of initialization is performed in the PYINIT call, and thereafter the events generated by PYEVNT all obey the rules established at that point. This improves the efficiency of the generation process, and also ties in with the Monte Carlo integration of the process cross section over many events. Therefore common-block variables that specify methods and constraints to be used have to be set before the PYINIT call and then not be changed afterwards, with few exceptions. Of course, it is possible to perform several PYINIT calls in the same run, but there is a significant time overhead involved, so this is not something one would do for each new event. The two older separate process generation routines PYEEVT (and some of the routines called by it) and PYONIA also contain some elements of initialization, where there are a few advantages if events are generated in a coherent fashion. The cross section is not as complicated here, however, so the penalty for reinitialization is small, and also does not require any special user calls.
Apart from writing a title page, giving a brief initialization information, printing error messages if need be, and responding to explicit requests for listings, all tasks of the program are performed `silently'. All output is directed to unit MSTU(11), by default 6, and it is up to you to set this unit open for write. The only exceptions are PYRGET, PYRSET and PYUPDA where, for obvious reasons, the input/output file number is specified at each call. Here you again have to see to it that proper read/write access is set.
The programs are extremely versatile, but the price to be paid for this is having a large number of adjustable parameters and switches for alternative modes of operation. No single user is ever likely to need more than a fraction of the available options. Since all these parameters and switches are assigned sensible default values, there is no reason to worry about them until the need arises.
Unless explicitly stated (or obvious from the context) all switches and parameters can be changed independently of each other. One should note, however, that if only a few switches/parameters are changed, this may result in an artificially bad agreement with data. Many disagreements can often be cured by a subsequent retuning of some other parameters of the model, in particular those that were once determined by a comparison with data in the context of the default scenario. For example, for annihilation, such a retuning could involve one QCD parameter ( or ), the longitudinal fragmentation function, and the average transverse momentum in fragmentation.
The program contains a number of checks that requested processes have been implemented, that flavours specified for jet systems make sense, that the energy is sufficient to allow hadronization, that the memory space in PYJETS is large enough, etc. If anything goes wrong that the program can catch (obviously this may not always be possible), an error message will be printed and the treatment of the corresponding event will be cut short. In serious cases, the program will abort. As long as no error messages appear on the output, it may not be worthwhile to look into the rules for error checking, but if but one message appears, it should be enough cause for alarm to receive prompt attention. Also warnings are sometimes printed. These are less serious, and the experienced user might deliberately do operations which go against the rules, but still can be made to make sense in their context. Only the first few warnings will be printed, thereafter the program will be quiet. By default, the program is set to stop execution after ten errors, after printing the last erroneous event.
It must be emphasized that not all errors will be caught. In particular, one tricky question is what happens if an integer-valued common-block switch or subroutine/function argument is used with a value that is not defined. In some subroutine calls, a prompt return will be expedited, but in most instances the subsequent action is entirely unpredictable, and often completely haywire. The same goes for real-valued variables that are assigned values outside the physically sensible range. One example will suffice here: if PARJ(2) is defined as the suppression factor, a value will not give more profuse production of than of , but actually a spillover into production. Users, beware!