\subsubsection{Concept of the event generator}

  The procedure of event generation consists of two steps.
  During the evaluation of cross section  by  \VEGAS~   \CompHEP~
writes down the calculated squared matrix elements into a binary file
{\it events\_}{\sc N}, where {\sc N} is the  session number.
These files are compact owing to occupation of approximately four
bytes per one event.  All \CompHEP~  settings 
and a current state of the random number generator are stored there too.

On the next step  stand-along command
{\it genEvents}  restores the event flow based on this file.
It repeats the \VEGAS~ session,  but instead of the real matrix element evaluation
 it reads the corresponding  values from the file.
  This trick allows one to repeat with a high speed the calculation of
particle momenta and event weights produced earlier during the
original Monte Carlo integration.

Note that the \CompHEP~  generates the partonic level  events.
 \CompHEP~ passes 
the task of fragmentation  to other programs like PYTHIA \cite{PYTHIA}.
 

\subsubsection{The {\it genEvents} command}

To restore events from the {\it events\_}{\sc N} file the user
should use the \\ {\it \$COPMHEP/genEvents} command. 
In being launched it  is waiting for   user
commands. These instructions are  read from  the standard input 
and  the outcome is directed  to the standard output.
  Any instruction should  be 
terminated by the end-of-line symbol (the \Enter~ key).

  The first instruction  should contain an event file name,
say,  {\it event\_1}.
If such a file exists and has an appropriate format,  {\it genEvents}
writes the process name, e.g. \\
\hspace*{2cm} {\tt PROCESS: e1,E1 \verb|->| e2,E2} \\  
Then the line(s) with a physical cut definition could follow.
The format of these lines is: \\
\hspace*{2cm}{\tt [function identifier]  [min.limit] [max.limit]}\\
See Section \ref{functions} for a format of the function identifier. The limits 
are just numbers. For the  case of the {\it S} function instead of
the values of squared  momentum  {\it Val}  the user has to put in  
the quantity $ Val/\sqrt{|Val|} $, similar  to the case of cut definition
in Section \ref{cuts}.

The last line of input may be empty or  contain a desired distribution 
specification. For the first case the weighted event flow will be created.
 Otherwise  the corresponding 
distribution  will be produced. The format of input which specifies a 
distribution
is the same as that for cuts, but contains an addition field which
defines the number of bins:\\
\hspace*{0cm}{\tt [function identifier]  [min.limit] [max.limit] [number of bins]}\\
The number of bins has not to exceed 300.

The {\it  genEvents}  command verifies  the input. But the user-friendly 
interface is not implemented here. For the case of wrong input
the error message appears and the program terminates.  So, in order to escape the 
repetition of typing we recommend to   store the input in a file
and pass it to {\it  genEvents} by \\
\hspace*{2cm}{\tt \$COMPHEP/genEvents \verb|<| user\_input\_file  }\\ or\\
\hspace*{2cm}{\tt  cat user\_input\_file | \$COMPHEP/genEvents }



Let us give an example of  {\it user\_input\_file}:\\

\begin{tabular}{l}
event\_1\\
A13 5 175\\ 
A15 5 175\\
M35 1 100 50
\end{tabular}\\

 It is an instruction to  build a 50 bin  distribution for the invariant mass of 
$3^{rd}$  and $5^{th}$ particles under  condition of  a 5 degree cut for the 
angle between the momenta of these particles and the collision axis.

To get  a matching  of particles  with  their momenta
 see the process string in  the corresponding 
protocol file {\it f\_prt\_}{\sc N}.

The output for the  distribution has got the following formats.\\
1. The process string:\\
\hspace*{1.5cm} {\tt PROCESS: e1 , E1  \verb|->|  e2 , E2 }\\
2. The {\it name} of the X-axis in double quotas, limits for the axis and
a number of bins:\\
\hspace*{1.5cm} {\tt  "Cosine(p1,p3)"  from $-1.0$ to   $1.00$ $  N\_bins=  10 $}\\
3. The name of the Y-axis:\\
\hspace*{1.5cm} {\tt Diff. cross section [pb]}\\
4. The sequence of $N\_bins$  lines for the averaged differential cross section
for each bin
 and its statistical uncertainty separated by "+/-":\\
\hspace*{1.5cm}  {\tt  ..............}\\    
\hspace*{1.5cm} {\tt  8.0978E+02  +/-   9.2786E+00}\\
\hspace*{1.5cm} {\tt ...............}



The following normalization of data is assumed: 
a sum of all values of the first column
multiplied by the bin size is equal to the cross section.

The graphical image of the distribution may be displayed 
by the \\ \mbox{\$COMPHEP/tab\_view} command.
One of the ways to use it is the long pipe:
\begin{center}
{\tt cat user\_input\_file | \$COMPHEP/genEvents |\$COMPHEP/tab\_view }
\end{center}
The options of the {\it tab\_view} program are described in Section
\ref{X11interface}. See Fig.\ref{plot-image} as an  example of plot
representation. 
One more  possibility  is to save the  intermediate result and then use
it:\\
\hspace*{2cm}{\tt   cat user\_input\_file | \$COMPHEP/genEvents > hist\_file}\\
\hspace*{2cm}{\tt    \$COMPHEP/view\_tab < hist\_file.}

To generate the event flow  the user has to  enter  an empty 
line instead of the distribution definition. After that the {\it genEvents}
program writes down the weighted events in the standard output.
The first six lines of output contain  general information about the
process, namely the process name, masses of particles,  structure function
records, the QCD scale, and   values of center-of-mass energy and rapidity. For example,
\begin{verbatim}
 PROCESS: e1 , E1    ->  e2 , E2
 MASSES:   0.000000E+00  0.000000E+00  1.057000E-01  1.057000E-01
 StructFun1: OFF
 StructFun2: OFF
 QCD constant scale: 9.12E+01, Lambda6=1.18E-01 GeV
 SQRT(S):   9.000E+01
 Rapidity:   0.000E+00
\end{verbatim}   
 The sign of  rapidity is defined in such a way  
that its change towards a positive value  corresponds to an  acceleration  
of the first  incoming particle. 

The seventh  line  contains the  column titles. The following lines 
contain columns of  numerical information about events.
In the first column the event  weights are written down. They are normalized so
that the sum of all numbers of the first column gives the
calculated cross section or decay width. 
  The other columns contain the components of three-momenta  of particles. 
The corresponding momentum and component numbers are described 
by the  seventh (title) line of the output. For example, {\it P2\_3} means
the third component of the second momentum. 
Note that the $3^{rd}$ component is assigned to the collision axis.
The first incoming particle has this component positive while the second
one has it negative. There are no columns for the momenta of incoming 
particles which are equal to zero by definition, for example, for the
$1^{st}$ and $2^{nd}$ components of momenta of colliding particles.

The  event flow output is normally very large, so we recommend to
redirect  the output to the subsequent  program for some processing  
\begin{center}
{\tt    cat user\_input\_file | \$COMPHEP/genEvents | userProcessing}
\end{center} 
A few such programs were created in the framework of \CompHEP~ project.
They are   disposed in the \$COMPHEP~ directory.


I. {\tt unweight.} It transforms
weighted events into unweighted ones. It needs a parameter $maxw$ which
specifies 
the maximum value of weights. Indeed this program  transforms the floating
number weight  into the  integer number one according  to  the following expression
$$  floor(\frac{weight}{maxw}) + p\left(\frac{weight}{maxw} -
  floor(\frac{weight}{maxw})\right)\;\;, $$
where $floor(x)$  function  rounds  $x$ downwards to the nearest
integer and
 $p(x)$ is the random function which equals 1 with probability $x$ and
zero otherwise. If the integer weight does not equal  zero then this event 
is written down into the output in the same format as the unweighted event
flow. The true maximum weight may be found in the protocol file.


II. {\tt filterD2.}  This program generates decays of one of outgoing 
particles into two others. It needs 6 arguments:\\
1) name of disintegrated particle;\\
2) name of the first decay particle;\\
3) numerical value of the mass of the first particle;\\
4) name of the second decay particle;\\
5) numerical value of the  mass of the second particle;\\
6) branching fraction for this decay mode.
For example, \\
\begin{center}
{\tt filterD2 Z e2 0.1 E2 0.1  0.034}
\end{center}
will generate  decays of the Z boson into  muons.
This program reads  event flow from the standard input and 
writes down generated events into the standard output. It can be used just 
after {\tt genEvents} and after {\tt unweight}.

III.  {\tt filterDN} This function can generate more complicated 
sub-decays, for example, \verb|1->3|  ones. It is assumed that before
its usage  the  events of  corresponding decay have been 
generated by \CompHEP,  transformed into the unweighted format,   and   stored in 
some file. The name of this file must be passed to {\tt filterDN} as the
first  argument. Numerical value of the corresponding   branching fraction
must be passed as the second argument.


 You can obtain a  wrong result  using some part of the whole 
event sample because  \VEGAS~ generates strongly correlated events 
according to the {\it Stratified Sampling} algorithm (see Section \ref{vegas}).
If events are written down in some file they may be mixed up by means of  
the {\tt \$COMPHEP/randomize} program. The first argument of this function
is a name of the file where events are stored. The randomized event flow
 is directed to the standard output.

The programs mentioned above, namely  {\tt unweight, filterD2, filterDN, 
randomize},  can have three optional  arguments. They
must be some integers which  are  used to re-initialize the starting point of
the random number
generator \footnote{ We use standard random number generator {\it drand48}.
}.
 
The generated event flow can be transformed to the table of distribution of
some physical variable  by means of the {\tt mk\_tab} program. This program
needs four arguments, namely, a name of variable in format of 
Section \ref{functions}, minimum and maximum limits of this variable 
and a number of bins, which cannot exceed 300.  The  {\tt mk\_tab} program 
reads the event flow in the standard input and writes the  generated table  down
to the standard output. This table can be transformed into a plot by means
of the {\tt tab\_view} utility.
  