\documentstyle[a4wide,12pt]{article}
\title{Test of the Event Builder}
\author{C. Diarra M.M. Aleonard\and translated by L.C. Pratt}
\date{draft}
\begin{document}
\maketitle
 
This document gives very simply an idea of the principle that was used
to simulate the events provided by the ROCO and explains how to use
the program which performs the simulation.  A complete document will
be issued later when the program is released.  In the mean time, your
suggestions will be welcome and will allow us to improve the program.
 
\section{PRINCIPLE}
\label{princ}
The program ``eb'' does random generation of some number of events
which is chosen by the user.  The different events produce 3 files:
\begin{itemize}
\item the data file (extension ``.dat'') which contains the equivalent of
      the words provided by the ROCO.
\item the spectra: each file of data results in 2 spectra
\begin{enumerate}
      \item a spectrum file with extension ``LGain'' which corresponds to
            the spectrum of gammas in the energy range 0--4 MeV
            (gain = 0.5 keV/channel).
      \item a spectrum file with extension ``HGain'' which is the spectrum 
            of gammas in the energy range 0--20 MeV.
            (gain = 2.5 keV/channel).
\end{enumerate}
      Spectra 1 and 2 are the ones that should be compared to the spectra
      output by the sorter.  One will therefore be able to tell if the Event
      Builder (EB) handled the file of data correctly.  In principle, the
      spectra produced by the program ``eb'' and those produced by the
      histogrammer should be identical if there are no errors in the
      treatment of the data.
\end{itemize}
 
\section{CONSTANTS AND CONVENTIONS}
 
\subsection{ROCO Event Format (edoc064, John Cresswell)}
 
\begin{itemize}
\item Trigger Header: the trigger item with address 0x34 (External
      sumbus) is not generated.  The value of the data word item with
      address 0x30 (Trigger type) will always be zero.
\item all the TAC words are fixed at the same value (10 ns)
\item qualifier bits (qHqL): qH is set to 1 for Compton suppressed and qL is
      set to 1 for PILE UP.  The default values are 0.
\item word count: the word for the End Subevent Token is included in the
      count. 
\end{itemize}
 
\subsection{Constants used in the Program}
 
\begin{itemize}
\item multiplicity: this is centred at RAW0=5 and varies between 2 and 10.
\item number of ROCOs = 3
\item number of Ge and BGO cards in each crate = 10
\item number of channels (ADCs) per card = 6
\item probability of Compton suppression = 1/2
\item maximum number of bgo hits in a pattern word = 3
\item it is assumed that for a Compton scattered gamma, ~60\% of the
      incident energy is detected in the Ge.
\end{itemize}
 
\section{MAGNETIC TAPE FILES}
 
The program ``eb'' uses the tape in the following manner:
 
\begin{itemize}
\item If the tape is initialised with ``eb'' and the tape is empty there is
      an EOM (End Of recorded Media) mark at the start. 
\item If there are files on the tape, the first thing on the tape is an EOF
      mark followed by the files.  The files are themselves separated by EOF
      marks.  Each file corresponds to one of the 3 files described in
      \S\ref{princ} above.
\item The last file on the tape is terminated by an EOM mark.
\item Note: At present the program can only be used with a 150 Mbyte
      streamer.  The functions ioctl() and fcntl() will be used in the final
      version of the program instead of making a call to the system command. 
\end{itemize}
 
\section{DISC FILES}
 
 There will be 3 files (if all the data are saved on disc) for each run
simulation on the disc: the data file and 2 spectrum files.  If the data are
written straight to magnetic tape, there will only be 2 files on the disc
(the 2 spectra), which may then be saved to tape.
 
The file with extension ``.log'' contains all the details of each event. The
option to log all the information about individual events must only be
chosen for a small number of events and was provided for checking this
program.
 
\section{FILE HEADERS}
 
There will be the same headers for both tape and disc files: one header
(entete) in ascii of 512 bytes at the start of the file an EOF header at
the end.
 
\subsection{The Data Files}
\begin{itemize}
\item Header: the header comprises the following fields:
 
      \begin{tabular}{@{---}lr@{--}ll}
      &  1 &  15 & file name                    \\
      & 16 &  30 & creation date (DD--MMM--YYYY)\\
      & 31 &  45 & record length                \\
      & 46 & 512 & space                        \\
      \end{tabular}
 
      The data file block size is fixed at 128 kbytes (128 kbytes = the size
      of the HSM, where 1 kbyte = 1024 bytes).
\item EOF header: The following fields are present:
 
      \begin{tabular}{@{---}lr@{--}ll}
      &  1 &   3 & ``EOF''  \\
      &  4 &  15 & space    \\
      & 16 &  30 & file name\\
      & 31 & 512 & space    \\
      \end{tabular}
 
\end{itemize}
 
\subsection{The Spectrum Files}
 
\begin{itemize}
\item Header: This comprises of the following fields:
 
      \begin{tabular}{@{---}lr@{--}ll}
      &  1 &  15 & spectrum name       \\
      & 16 &  30 & creation date       \\
      & 31 &  45 & number of channels  \\
      & 46 &  60 & first channel number\\
      & 61 &  75 & last channel number \\
      & 76 & 512 & space               \\
      \end{tabular}
 
\item EOF header:
 
      \begin{tabular}{@{---}lr@{--}ll}
      &  1 &   3 & ``EOF''      \\
      &  4 &  15 & space        \\
      & 16 &  30 & spectrum name\\
      & 31 & 512 & space        \\
      \end{tabular}
 
\end{itemize}
 
\section{CHOICE OF GAMMA ENERGIES}
 
The point of the simulation is to verify in a simple fashion the handling
of the data from the ROCO by the event builder.  The chosen method is to
compare the 2 spectra obtained once the event builder has rejected bad
events and gammas that have undergone Compton scattering.
 
The gamma energies were calculated according to a simple formula in order to
get the clearest spectrum possible:
\begin{quotation}
E = RAW $*$ (E0 + 10.0 $*$ SUPP + BGOSUMBUS)
\end{quotation}
where \\
RAW = raw multiplicity\\
SUPP = number of clean Ge detector hits (i.e. no Compton scattering)\\
BGOSUMBUS = number of Compton scattered gammas detected 
\begin{quotation}
BGOSUMBUS = 1/2 $*$ RAW
\end{quotation}
This choice is arbitrary.  It means that 50\% of the gammas undergo Compton
scattering. 
\begin{quotation}
SUPP = RAW -- BGOSUMBUS
\end{quotation}
Note: These calculations are valid since a Compton scattered gamma is
assumed to remain in the BGO shield of the Ge where it was detected.
 
It can be seen from the gamma-ray energy formula that all the events with
the same RAW multiplicity will have the same energies.  This energy is
unique because SUPP and BGOSUMBUS themselves depend upon RAW.
 
For example, suppose we generate 10 events with 5 events of RAW = 4 and 5
others with RAW = 7 we will have one spectrum with 2 gamma-rays, since all
the events of the same multiplicity contribute to the same channel.
 
E0 is a constant (E0 = 500 keV) and can be modified in the program.
 
\section{SPECTRUM PRODUCTION}
 
The spectrum is updated continuously as the events are generated.  In
fact, 2 spectra are generated for each data file, both comprising of 8192
channels.
 
The first spectrum is only for gammas in the energy range 0--4 MeV and the
second from 0--20 MeV.
 
\begin{itemize}
\item rejected gammas: all gammas where Compton suppression or pile-up has
      occurred are rejected.
\item rejected events: all events with errors in are rejected.
\end{itemize}
 
The possible errors that may appear in an event are as follows:
\begin{enumerate}
\item One of the error indication bits (EE) is set to 1
\item BAD FOLD: the multiplicity given by the Trigger does not tally with
      that found by counting the words from the ROCO.  This means that not
      all the expected words were received.
\item BAD END: one of the ROCO's has not sent its End Sub-Event Token.
\item ROCO missing: a ROCO has not sent any data at all.
\end{enumerate}
 
\section{UTILISATION OF PROGRAM eb}
To run the program, type ``eb''.
 
\subsection{Create or modify config-file}
This option permits the creation or modification of the configuration file.
All the information about the location of different detectors is in this
file.  For each group there is an entry to indicate the VXI crate number,
slot number and channel number on the Ge or BGO card.
 
Note: slot number 1 corresponds to the first BGO card in the VXI
crate.  Slot 2 is the Ge card to the right of slot 1 and slot 3 the
following BGO, etc.  This slot number is an arbitrary one needed to
provide the alternate sequence BGO-GE.
 
Creation options for the configuration file:
 
\begin{itemize}
\item Automatic creation: The Ge and BGO cards are assumed to occupy
      alternate slots in the VXI crate in the order BGO-GE-BGO-GE-BGO-\ldots
      The channels (6 per card) in the same EUROGAM face and for 2 adjacent
      cards correspond to the same group.  E.g. in crate 1, channel 4 of the
      BGO card in slot 1 and channel 4 of the Ge card in slot 2 correspond
      to group 4.  This methodology allows, therefore, the creation of an
      entry in the configuration file corresponding to each group.
 
\item Step by step creation: The user must enter the crate number, the slot
      number,\ldots the type of shield (5 or 10 BGO), etc.\ldots However,
      the automatic creation option is recommended in preference to this one
      at present, when the detectors are ordered sequentially.
 
\item Modify config-file: If a detector is repositioned, it will be
      necessary to modify the config-file by giving the detector number
      concerned and the new location parameters for the detector (crate,
      slot, channel, \ldots)
\end{itemize}
Note: it is possible to create additional configurations by modifying the
initial file (having saved the original file under another name before the
modification).  
 
The configuration file is only created on the first use of the program eb.
The extension ``.cfg'' is added onto the name of the file given as the
configuration file.
 
\subsection{Magnetic tape initialisation}
 
To be used only if it is desired to save the data file on magnetic tape.
This option serves to initialise a new tape and so must only be used once.
 
\subsection{Event simulation}
 
This allows the generation of $n$ (the program will request the number $n$
as input) events.  For each of these events, the multiplicity is chosen
randomly in the range given above.  This range can be altered in the
program. 
 
\subsection{Saving a spectrum on magnetic tape}
 
The spectra created by the simulation are kept on disc.  It is necessary to
use the option ``restore spectrum on tape'' in order to put the spectra on
the tape with the data file.  This option must be used twice to save the 2
spectra (low and high gain).
 
\subsection{File naming conventions}
 
Data file name: Give the name under which you wish to keep the spectrum in
the header to identify the data file.  The extension ``.dat'' will
automatically be added on the end.  For example, to generate events for
which the error type is eH=1 (the most significant error bit from the ROCO
is set to 1), it is necessary to enter:
 
\begin{enumerate}
\item The file name where all the words output by the ROCO's will be saved:
      for example eHset.  The name of the file will then appear in the
      header in the form eHset.dat.  If the data are saved on disc the name
      of the file will be eHset.dat.
\item The name of the spectrum files: it may be different to the ``.dat''
      file.  Equally, the same name, eHset, may be chosen for simplicity.
      After the event simulation there will be 2 spectra on disc: eHsetLGain
      and eHsetHGain.  The component ``LGain'' or ``HGain'' is added
      automatically to the spectrum name.
\item The names of the files to save: to save the 2 disc spectra onto tape,
      the full names must be given, e.g. eHsetLGain to save the low energy
      spectrum.  To save the second spectrum the spectrum name must be given
      as eHsetHGain.
\end{enumerate}
\end{document}