\subsubsection{Concept of user program implementation}

We provide the user with a possibility  
to attach his own codes to the {\it n\_comphep\_f(c)} and {\it genEvents}
programs.  In this way you are able to\\
1) expand the  set of phase space functions  for  cuts and
histograms\\ 
2) implement  new structure functions.

\CompHEP~ archive file {\it num\_f(c).a} contains some patch programs. 
When you create your version of these programs and pass the names 
of its object files to the linker, they will be embedded 
into the executable file. 

In the case of {\it n\_comphep\_f(c)} command the following
instruction does this job:\\  
\hspace*{2cm}{\tt \$COMPHEP/make\_\_n\_comphep  f(c) userObjectFiles.o} 


It is assumed that the above command  is started from within the
user's directory 
{\it results}  which contains  sources or their archives.

The {\it genEvents} file is disposed in the {\it \$COMPHEP} directory 
and generally cannot be modified by the user. But one could create 
his own version of this program. In this case use \\     

{\small \tt f77 -o userEvents  \$COMPHEP/events.o userObjFile.o \$COMPHEP/num\_f.a}


\subsubsection[\Fortran~ case]{\Fortran~ case\footnote{ 
Below we insert  parameter  type  definitions into  headers of the \Fortran~ 
routines. It is done for brevity only  and contradicts to the \Fortran~  style}} 

  The user  phase  space function  is evaluated by\\
\hspace*{2cm}{\tt   REAL*8 FUNCTION USRFUN(CHARACTER *9 TEXT) }

The patch is disposed in the file {\it \$COMPHEP/f\_source/usr/u\_var.f}. 

     This function is called by {\it n\_comphep\_f} and 
{\it \$COMPHEP/genEvents} programs  if the phase space
function whose name begins with the 'U' character is used (see Section
\ref{functions}). The characters following   'U' are passed to
the {\it USRFUN} routine as its argument.

To  create this function one  needs to  know the particle momenta.
They are  stored in
\begin{center} {\tt  COMMON/PVECT/ REAL*8 P(0:3,100) }\end{center}
 The first argument of array {\it P} is a Lorentz momentum component.
$P(0,N)$ is the energy of the $N^{th}$ particle. 
We have $P(0,N)>0$ as for 
incoming as for outgoing particles. 
In the case of  collision process  $ P(3,N)$ is a projection of the
particle space momentum onto the collision axis. The direction of this axis is
chosen so that   $P(3,1) > 0$ and $P(3,2) < 0$.

The second argument of this array is a  momentum  ordering  number. 
The first  momentum numbers  are assigned to incoming particles and the 
subsequent ones  are   assigned to   outgoing particles. 
The  numbers of incoming and outgoing particles and 
a  correspondence between  the   particle name and the  momentum number 
may be determined by means of service functions described in 
Section \ref{out-fort}.


The work of user structure function is controlled by a set of routines.
The patches for them 
are disposed in {\it \$COMPHEP/f\_source/usr/sf\_prv.f}. 
All of them should  be realized by the user: 
  

1.    {\it LOGICAL FUNCTION  P\_PRV(CHARACTER*6 P\_NAME) }\\     
      returns  {\it TRUE} if the user structure function can be 
applied to the {\it P\_NAME} particle.
 It is used to create the  menu of possible structure functions 
      for the  particle {\it P\_NAME}. 

2.    {\it SUBROUTINE M\_PRV(I)}\\
       is called for the user input of the structure function parameters
      just after the user structure function  has been chosen. 
       It is assumed that this routine 
saves values of the entered parameters in some COMMON  for
subsequent usage  in  N\_PRV described below.   The argument {\it 'I'} here 
and in the following  means an  incoming  parton  number. It can be 1 or 2. 



      
3.    {\it CHARACTER*60 FUNCTION N\_PRV(I)}\\
      returns the structure function name. If the structure
      function has a few tuning parameters then  the values of these 
      parameters must be included in the returned  name. \CompHEP~ uses the structure 
      function name to keep  information about parameters.


4.   {\it  LOGICAL FUNCTION R\_PRV(I,CHARACTER*60 NAME, REAL*8 CMASS, REAL*8 BE)}\\
      checks {\it NAME}. If  {\it NAME}  has the same format as the one  
produced by {\it N\_PRV()},  {\it R\_PRV()} should  read the parameter values,
 store them in some global variables for subsequent usage,  and 
      return TRUE. Otherwise FALSE is returned.
     {\it  REAL*8 CMASS} and {\it  REAL*8 BE} are outgoing parameters.
     The first one must be equal to the mass on the composite particle 
     which constituents are described by user's structure function. 
     The second one  informs 
     \CompHEP~ that the structure function is singular as

             $  (1-X)^{(BE-1)} $,  where $0<BE\leq 1$.\\
In the nonsingular case  $BE=1$ must be returned.
              
5.  {\it REAL*8 FUNCTION C\_PRV(I,REAL*8 X)}\\
       returns the value of structure function divided by $BE*(1-X)^{(BE-1)}$. 
    Here  $X$ is the Feynman scaling variable. 
It is assumed that possible structure function parameters having been stored 
by {\it R\_PRV} are used for evaluation.  The structure function is
normalized so that 
$$ be(1-x)^{be-1}c\_prv(i,x)dx$$ 
is a probability to find the $i^{th}$  parton with fractions 
$[x, x+dx]$ of initial momentum.
 

In the simplest case, if the user would like to implement a new 
structure function without singularity and extra parameters, he can just take a
copy of the  {\it \$COMPHEP/f\_source/usr/sf\_prv.f} file, improve  {\it
P\_PRV} so that it returns $'.TRUE.'$ anyway, and  rewrite  originally trivial
{\it C\_PRV}.


\subsubsection{\C~ case} 


  The user   phase  space function has a prototype \\
\hspace*{2cm}{\tt   double usrfun(char * name) }\\
The patch is disposed in the file {\it \$COMPHEP/c\_source/num/userFun.c}. 
     This function is called by {\it n\_comphep\_c}   programs  if the phase 
space function whose name is started from the 'U' character is used (see
Section \ref{functions}). The characters following  'U' are passed to
the {\it usrfun} routine as its argument.

 Particle momenta which are needed to evaluate  {\it usrfun} 
are stored in the global variable \\
\hspace*{2cm}  {\tt double pvect[400] } \\
The  $m^{th}$ component of $k^{th}$ momentum occupies the $m+4*(k-1)$ position
in {\it pvect}. We assume that 'm' varies from 0 to 3 and the 'k' momentum  
counter  starts from 1. The agreement about momentum signs is the same 
as in the \Fortran~ case. The  number of incoming and outgoing particles and
the correspondence between  the   particle name and  momentum number
can be determined by means of service functions described in
Section \ref{out-c}.



The work of user {\it structure function} is driven by a  set of routines
similar to those of the \Fortran~ case.
All of them have to be realized by the user if he would like to implement 
a particular structure function. Patches for these routines are disposed in \\
\hspace*{2cm}{\it \$COMPHEP/c\_source/num/strfun/sf\_prv.c}.\\
 This file contains:
  

1) {\it int p\_prv(char *particleName)}\\
      returns  {\it 1} if the user structure function can be 
implemented to the \mbox{\it  particleName} particle. Otherwise 0 should 
be returned.
 It is used to create a menu of possible structure functions;

2)    {\it void m\_prv(int i) }\\
      is called for the user input of the structure function parameters
      just after the particular structure function  is chosen. It is assumed
that the input is saved in some static variables.
The argument {\it 'i'} here and below
means an  incoming  parton  number. It could be 1 or 2;

3)    {\it void n\_prv(int i, char * funcName )}\\
      returns the structure function name. If the structure
      function has a few tuning parameters then  values of these 
      parameters have to  be included in {\it funcName}. \CompHEP~ uses the structure 
      function name to keep  information about parameters;


4)   {\it int r\_prv(int i, char *funcName)}\\
      checks {\it funcName}. If  {\it funcName}  has an appropriate  format,
  {\it r\_prv} must read  the value of
parameters, store them in some global variables  and 
      returns 1. Otherwise 0 is returned;

5)  {\it int mass\_prv(int i)}\\
    returns the mass of the composite particle which constituents 
    are described by this structure function.

6)    {\it double be\_prv(int i) }\\  
     performs needed  initializations  before structure function evaluation.
     It returns parameter $be$ which  informs 
\CompHEP~ that the structure function is singular as

             $$  (1-x)^{(be -1)}; $$

7)  {\it double c\_prv(int i, double x)}\\
    returns the value of structure function divided by $be(1-x)^{(be-1)}$, 
      where $x$ is the Feynman scaling variable. 
It is assumed that possible turning  parameters have been stored 
by {\it  r\_prv} in some static variables. 

In the simplest case, if the user would like to implement a new 
structure function without singularity and extra parameters, he may  take a
copy of the {\it \$COMPHEP/c\_source/num/strfun/sf\_prv.c} file, improve  {\it p\_prv}
 so that it returns $1$ in any case, and  rewrite the  originally  trivial
{\it c\_prv} function.
 
