\section{EvtGen interface}
\label{sect:interface}
\index{API}



The EvtGen package supplies a test program, testEvtGen.cc, which
provides a main routine that tests various functions of the
EvtGen package. However, a user of the EvtGen package is not
expected to use this program in his application. Instead 
it is expected that the event loop needed to generate the 
events is written externally and invokes routines in EvtGen 
to do initialization and event generation. This section
describes the various functions that makes the user 
interface. 

The interface is provided through the class {\tt EvtGen} that
provides member functions to do initialization of the
generator, normally prior to generating events, and to
generate events. It also provides access to controll of
various configurations parameters that are used to control
the generator.

Initialization of the generator is done with the function
\begin{verbatim}
void EvtGen::init(char* decay, char* pdt, char *udecay);
\end{verbatim} 
where {\tt decay} is the name of the decay table to use, 
{\tt pdt} is the name of the particle property file that is
used by EvtGen and {\tt udecay} is the optional name of a
user decay table that is read after the main decay table,
{\tt decay}. If {\tt udecay} is either an empty string or
an NULL pointer then no user decay file is read.
If you want to read additional decay files this can be
done with the 
\begin{verbatim}
EvtDecayTable::ReadDecay(char * decay);
\end{verbatim}
member function. 

EvtGen can after this initialization be asked to generate one
event at the time by calling the member function
\begin{verbatim}
void EvtGen::event(int stdhepid,LorentzVector p,LorentzVector d);
\end{verbatim}
where {\tt stdhepid} is the particle number according to the stdhep
particle numbering scheme. {\tt p} is a four-vector giving the 
initial momentum and energy of the initial particle. Similarly.
{\tt d} gives the initial vertex and time for the initial particle.
This function will generate an event and then store it in the
stdhep comon block, {\tt hepevt}. This is the most convenient 
form for having EvtGen to generate an event. In some test that
are internal to EvtGen it is not an advantage to have EvtGen
fill the stdhep common block. Instead these test work with
the internal EvtGen structures. Here the user will need to create the
initial particle and then generate the decay with the
memebr function
\begin{verbatim}
void EvtGen::event(EvtParticle* p);
\end{verbatim}
Note that here the user is also responsible for destroying the 
the created decay structure. This is done by
\begin{verbatim}
p->deleteTree();
\end{verbatim}

For the convienence of users more familar with fortran, we
have also provided a fortran frontend to the {\tt EvtGen} 
interface described above.  There are three necesary files:
\begin{itemize}
\item {\tt top.cc}
\item {\tt myfunc.F}
\item {\tt evtgenevent\_.cc}
\end{itemize}

The first of these simply is the main that calls 
{\tt myfort.F}.  In order to link with a C++ compiler,
there must be a main writen in C++.  {\tt evtgeninit\_}
and {\tt evtgenevent\_}
are the routines that actually call the {\tt EvtGen:Init}
and {\tt EvtGen:Decay} routines.  These routine handles
the initialization of EvtGen as well as
the deletion of the particle tree from memory when it
is no longer needed.  {\tt evtgenint\_} takes three 
arguements, and is declared as
\begin{verbatim}
void evtgeninit_(char *decayname, char *udecayname, char *pdttablename)
\end{verbatim}
{\tt evtgenevent\_} also takes three
input arguments:
\begin{verbatim}
void evtgenevent_(float *pos, float *tim, int *parent) 
\end{verbatim}
{\tt pos} is an array that contains the initial x, y, and
z position of the particle.  {\tt tim} is the production
time of the particle.  {\tt parent} is the standard HEP
number of the particle.  The EvtGen output is returned
in the standard HEP common block defined in {\tt stdhep/stdhep.inc}
{\tt myfort.F} is the fortran
routine that should be modified to suit your needs.  By
default it will generate one event with a $B^0$ meson
as the parent.  

It is straightforward to modify this interface structure
in order to include EvtGen inside of a larger fortran
program.  {\tt top.cc} should be modified to call
whichever routine is currently the top fortran routine.
The routine {\tt myfort.F} can then be modified to suit
your needs. 








