Kloe Memo 128-98
December 1997
A. Antonelli, C. Bloise
The program runs everywhere the CERN together with the YBOS and the S_I Libraries have been installed, and it requires, in the most updated version, to accede the Kloe Database to retrieve the basic parameters of the detector, related to both, the apparatus geometry, and the sub-system response simulation.
The GBATCHDB and GEANFILASTDB files contain most of the basic code. The INTERFACE file contains the code for the loading of the parameters from the Database. The main program for the interactive version of GEANFI (GXINTDB) may help everybody to get started with GEANFI and to display the details of the simulation of complicated topologies.
The first version of GEANFI was written in 1992 and it is described in the Kloe Note 52/93. The system has been developed with continuity over the years, and the modifications generally lead to backward incompatibilities. The user is therefore invited to read the $VERSION directory contained in the current GEANFILAST.CMZ file where all changes are described in some detail.
The development and the maintenance of GEANFI are possible only thanks to the continuous collaboration of the Kloe members who use the program and contribute their feedback to the maintainers at LNF. It is of course impossible to mention all of them, and we wish to thank everybody and expresses the hope that they will continue to help us.
GEANFI, as the name suggests, is based on the GEANT code, version 3, originated from Brun and Andy McPherson at CERN in 1982 during the development of the OPAL simulation program.
Antonella Antonelli and Caterina Bloise wrote the greatest part of the detector description, together with the procedures to simulate the detector responses, to obtain and to store the information needed to accomplish the different studies, to create the YBOS banks for the output. Vincenzo Patera implemented the tracking procedure inside the drift chamber, that takes into account of the multiple scattering due to the wires, and calculates the drift times for each cell. Patrizia De Simone provided the description of the time-to-space relations by the analysis of the results of the GARFIELD simulation of the behaviour of each kind of cell existing in the drift chamber. Won Kim provided the basics to simulate the calorimeter responses, concerning timing and energy as well. The physic generators and the treatment of processes like the Kshort regeneration or the kaon interactions at the interesting energies have been developed thanks to the work of different authors. The original Phi decays are due to Alessandro Calcaterra and the code was developed later by Caterina Bloise; the Phi decays into f0-photon have been included thanks to Won Kim; the first Bhabha generator was written by V.Glagolev and the more sophisticated version was due to Elena Drago and Graziano Venanzoni; the cosmic muon generator has been created by Stefano Di Falco thanks also to the work done by Elena Drago and Andrea Smilzo, and the machine background has been implemented by Vincenzo Patera . The treatment of the kaon interactions, stimulated by Rinaldo Baldini, has been studied in the Andrea Michetti thesis and then re-attached by Maurizio Palomba. The Kshort rare decays (pai+pai-photon,3pai0,photon-photon), the Klong into pai+pai-photon, and the matrix element for the pai+pai-pai0/pai+pai-photon channels have been included thanks to Sergio Sinibaldi and Tommaso Spadaro. The routines related to the data retrieving from the Database have been written by Patrizia De Simone who takes care of the Database itself.
Many people contributed to the program development in these years, so that the list can be incomplete and we apologise for any omission.
Despite our efforts, the documentation is still far from perfect, we expect that the feedback from everybody will make it really useful.
Caterina Bloise
March 15 1997
Within each section, the main system functions or the details of subroutines are described. Subroutines which are not necessary for an understanding of the program flow have been omitted.
Special sections are devoted to the description of the input data cards, to the possible choices for the output, and to practical advices for running and for data retrieving by the analysis programs.
The framework offered by GEANT for event simulation is properly documented and it constitutes the basics to understand the GEANFI program flow. We will not repeat such a description here, apart from some reminders useful to understand the structure of the GEANFI procedures. Sometimes we will indicate inside square brackets the relevant section of the GEANT documentation where more information can be found.
Two main programs are available, for batch type operation (GBATCHDB), and for interactive operation (GXINTDB), both binary and source, in the GEANFI_EXE reference directory at LNF and on the AFS Kloe area both, at LNF, and CASPUR. The binaries refer to HP-UNIX and OSF platforms and are stored in different areas, pointed by the logical names set by the Kloe " setup offline '' command. The source is provided on the same disks in case the user wants to modify it, in the GEANFI_CMZ and in the GEANFI_SRC areas.
The main program allocates the dynamic memory for ZEBRA , for YBOS and HBOOK, it retrieves Database information via a call to the INTERFACE routine, and passes control to the three phases of the run:
in each of the three phases GEANFILASTDB provides the procedures in the appropriate routines.
The initialisation is controlled by UGINIT who has the responsibility:
The processing phase is triggered by a call to the subroutine GRUN which, for each event to be processed:
The event processing starts with a call to GUKINE that generates or reads ( [IOPA]) the kinematics of the event following the user's prescriptions.
The event processing continues with a call to GTREVE that performs the following operations for each vertex in turn:
Secondary products generated by the current particle are processed before proceeding to the next particle.
The data structure JXYZ, containing the coordinates of space points along the tracks, can be filled during tracking ( [TRAK]) according to the data card SWIT. The storage of such an information can be useful in the interactive version because it allows to display the particle trajectory inside the apparatus.
Once the tracking of the entire event has been completed, a call to GUDIGI starts the simulation of the detector responses using the information recorded during particle transport.
At the end GUOUT performs the calling sequence to prepare, fill and output the YBOS banks, requested by the user via data-cards, to be attached by the ANALYSIS_CONTROL (A_C) programs.
Other routines called during the tracking phase triggered by GTREVE should be mentioned for completeness:
The termination phase is under the control of GULAST. It consists of a call to the subroutine GLAST which computes and prints some statistical information (time per event, use of dynamic memory, etc.).
Caterina Bloise
March 15 1997
Different kinds of events can be grouped in one run, according to the data cards provided by the users. The GEANFI program contains the code to generate the physics of interest at the Daphne energy:
The most updated Bhabha generator is described in the Kloe Memo 59/96. It consists basically, like the other event generators described in this section, of two procedures: one driven at initialisation time by UGINIT and one by GUKINE to extract and to store the particle kinematics and the particle origin in the proper GEANT structures (KINE/VERT banks). At initialisation time EGENER(-1) calculates the approximate cross sections concerning both, the electron-positron events, and the electron-positron-photon events. The calculation makes use of the parameters read via data cards, that are, the minimal/maximal zenithal angle of the scattered electron (c.o.m. frame), and the minimal/maximal beam-energy fraction compatible with an "hard'' photon emission. The default values for those parameters are 1-179 degrees and 0.01-1. The EGENER(0) routine, called by GUKINE, generates an electron-positron or an electron-positron-photon event according to the expected fraction calculated by EGENER(-1). Once a radiative event has been selected, the procedure selects/rejects the extracted topology according to its frequency in the framework of the alfa-order calculation of the radiative corrections, taking into account of the presence of the phi-resonance too. The approximate total cross section given by EGENER(-1) is used also to calculate the fraction of Bhabha when these are only one part of the whole sample.
The cosmic muon generator is driven by the COSM data card, containing the flag to switch on/off the procedure and the minimal muon energy. The default value for this energy is 200 MeV. MUONIN is called by UGINIT and it computes the muon rate taking into account of their minimal energy and the apparatus acceptance. The prescriptions to extract both, the muon energy, and its direction, follow the Dar's paper, Phys. Rev. Lett. 51 (1983) 227. The muon origin is randomly-extracted on a spherical surface containing the entire coil, having a radius of 478 cm. This choice is dictated by the need to reproduce the details of both, the energy spectrum, and the arrival directions of the muons crossing the Kloe detectors. These details depend in fact on the coil described in the GEANFI program. MUGEN is called by GUKINE to fix the muon momentum and its vertex, by using the tables prepared by MUONIN. Due to the large radius of the surface containing the entrance points of the muons, only a fraction of these muons eventually reaches the detectors. To obtain a fixed number of detected muons the GEANFI procedure must be triggered 1.3 times more.
In the past the machine background studies have been accomplished by filling the KINE/VERT structures with the information coming from the TURTLE simulation code. Such a code has been customized by E. Gero to track the particles inside the magnetic elements corresponding to the Daphne layout, and it simulates the electromagnetic interactions of the electron/positron in the different machine sections. The relevant information for our experiment , e.g. the spectrum and the direction of the particles exiting from the beam pipe in the interaction region, was stored in the proper structures to allow the further tracking of the particles inside the apparatus, and the simulation of the detector response by the GEANFI program. Later, Vincenzo Patera established a procedure to randomly extract this information on the basis of a parameterisation of the relevant TURTLE results. The description implemented in the Montecarlo concerns both, the electron/positron events due to the Coulomb scattering, and the electron/positron/photon events due to the Bremsstrahlung. These processes result in high/intermediate energy releases in the apparatus and are the most interesting for the Kloe data acquisition, and for the study of the filtering criteria to adopt by the triggering scheme of the Kloe experiment. The generation is driven by the MCBK data card, containing the flag to switch on/off the procedure. The fraction of events due to Coulomb scattering and to the Bremsstrahlung can be set by the PLUP card: the third and the fourth values refer to the rates of these two processes, respectively. The default values are 701 and 598 KHz, and they are expected at the Luminosity of 5*10**32 cm**-2 s**-1.
The muon pair generator is activated by the MUMU data card with the related four parameters. The first one is used to switch on/off the generation procedure, the following two are the minimal and the maximal zenith angle in the center of mass frame, and the fourth can be used to change the actual rate of the events, if the cosmic muons are generated together with Phi decays. The MUPAIR routine is called at initialisation time to compute the cross section for the requested angular range and then it is called by GUKINE to establish the muon kinematics and to store the values in the GEANT data structures. The cross section is used, in the case of mixed generation, to fix the relative amount of muon pairs; the ratio obtained is then adjusted if the MUMU directive specifies a scaling factor different from one.
The muon-pair-plus-one-photon events constitute a source of background for the f0-photon searches, when the f0 decays into charged pions. Such a generator is driven by the F0BK card, and the second value in the data card can be used to switch on/off the generation of these events.
The GEANFI program can generate the Phi decays into:
It is possible to switch on/off each of those channels by using the PHID data card. In turn, for each of these decays, it is possible to choose the channels for the secondaries. A routine, ADJBR, called by UGINIT, handles the information read via data cards to compute the relative branching fractions of the required channels taking into account of both, the selected Phi decays, and the selected channels for the secondary particles. The kinematics of the decays are not only dictated by the phase space, like in the GEANT code, but a description of the proper dynamics is furnished as well.
It is possible to collect in the same run Phi decays, Bhabha events, cosmic muons, machine background or any combination of these channels. Proper data cards have been created to specify the kinds of events to generate. These cards contain, besides the flags to switch on/off each channel, the parameters needed to choose the relative branching fractions. The default parameters refer to the full luminosity of Daphne, e.g. 5*10**32 cm**-2 s**-1, and to the default settings of the selected generators mentioned above.
Of interest for a realistic reconstruction of the Kloe events is the procedure to add to the main Phi-decay triggers the information, if any, due to other processes that can overlap in time the main event. In fact we expect some contribution from Bhabha and machine background piled up with the hits in the chamber, and the energy release in the calorimeter, due to the particles coming from the Phi decays. The addition of these extra-particles is a CPU-consuming procedure and for this reason a set of parameters can be changed to obtain different amounts of pile-up. Moreover, to increase the readability of the output, the procedure cancels out the information related to those extra-particles that are not eventually detected in the apparatus.
Sometimes, to study the detector responses is useful to follow single particles with special values of both, the direction, and the momentum. The data card SPAR allows to pass to the program the characteristics of such a particle which can have fixed or uniformly-random-distributed origins and momenta.
Finally, in some case, like the study of the machine background, external generators need to be interfaced to the GEANFI program to obtain the final responses of the apparatus. To this purpose the GEANFI data cards can be set to trigger the events starting from the kinematics read from a ZEBRA file containing at least the KINE/VERT banks. Such a procedure has been used in the past also to study the simulation of the detector responses. In that case the procedure allowed to obtain different detector responses without any re-tracking of the event itself.
Caterina Bloise
March 15 1997
The generated particles, stored in KINE/STAK banks, are tracked by GEANT through the different detector material. At event level tracking is performed by the subroutine GTREVE called by the user routine GUTREV. GTREVE loops over the tracks and gives the control to the routine GTRACK that performs the tracking through the volumes identifying the volume boundaries and the materials. For each tracking step various physic processes, depending on the particle nature, are taken into account such as: energy loss, multiple scattering, hadronic interactions, decay probability etc. The step size depends on the particle properties and on the tracking medium parameters and are calculated by GEANT. Once the step has been decided, transport proceeds along straight line for neutral particle and along helix for charged one. The transport is performed by GHELIX3 routine in case of uniform fields and by GRKUTA routine for inhomogeneous fields. Actually we have two program versions one for constant field of 6 KGauss along Z (GBATCHDB.EXE, GXINTDB.EXE) and a second one that uses a fine field map (GBATCHFM.EXE, GXINTFM.EXE). The GUSTEP routine is called at the end of each tracking step and different actions are taken (some of them under DATA CARDS control):
Concerning the tracking in the drift chamber a different approach has been taken. To do not simulate in the geometry more than 50,000 wires which is very CPU expensive, a dedicated code has been written (KLOE note 103). This code communicates with the standard GEANT structure (material banks, particle properties etc.) through GEANT common blocks and uses standard GEANT routines to treat particle interactions. As the particle enters the drift chamber volume, the control is taken by this code (routine TRACCE) that propagates it taking into account cell dimensions and wire positions. At the end of the drift chamber the usual GEANT tracking is restored.
Antonella Antonelli
March 15 1997
The Detector Response Simulation
As it has been mentioned in the Introduction, the simulation of the detector responses is triggered by the GUDIGI routine, after the completion of the entire tracking procedure.
A set of routines are called at this stage to perform the simulation for the different detector sub-systems, namely the drift chamber, the calorimeters, and the QCAL quadrupole instrumentation.
The drift chamber TDC values are computed looking at the position of the minimum-approach point on respect to the field wires of each cell traversed by the particles in the event. Such a position is converted to a time using the time-to-space relations described by different sets of parameters corresponding to the different cell shapes envisaged in the drift chamber. The parameters have been computed by the analysis of the results of the GARFIELD program. This code allows to study the driftage of the electrons in the electric field corresponding to the positioning of field and sense wires inside the chamber, taking into account of the gas mixture and of the operating conditions (pressure, temperature) as well. In the Kloe drift chamber the cell shape changes with the z position and with the radius: to handle this point cells with really different field configurations, actually 216 cell shapes, have been studied separately to obtain the complete set of time-to-space relations used by GEANFI. Besides the time-to-space relations, the TDC simulation includes the handling of the uncertainty due to the ionisation process itself, and the propagation time of the signals along the wires. Cells crossed by more than one particle (or twice by the same particle) are assumed to register the signal coming from the first access only.
The TDC values of the calorimeter, a lead-scintillating fiber calorimeter, are computed on the basis of the crossing times of each particle in each fiber. To take into account of the uncertainty due to the photoelectron statistics, both in time, and in energy, the energy release is translated into an average number of photoelectrons using the results of the test-beam and the cosmic-ray-stand data, and the average number is then replaced by the final number by applying the poissonian statistics. The crossing times are converted in a set of scintillation-times for the photoelectrons taking into account of the emission-light-curve of the scintillating material used in Kloe. Then the propagation times along the fiber are added to the scintillation-times and those belonging to same cell are grouped together. The TDC value for each cell is the time corresponding to a fixed percentage of the collected signal to simulate the behaviour of the constant-fraction discriminators. The ADC values are simulated by summing up the contribution of each photoelectron belonging to the same cell. The entire procedure is driven by two other parameters, one being the ADC-gate-length, the other the integration time over which the discriminators operate.
The simulation of the QCAL response, as it is at present, mimic the simulation procedure established for the Kloe calorimeters. QCAL has photomultipliers on one side only and to obtain the z-coordinate the scintillation light is also sent to the second-next cell. In practice the cells are connected two by two. Apart for the grouping procedure of the information to be examined together, the response simulation described in the previous paragraph is applied also in this case.
Caterina Bloise
March 15 1997
The data management chosen by KLOE is based on YBOS package an all the analysis programs are based on it. On the contrary GEANT is based on ZEBRA and a lot a user routines are provide as an interface to the data structure to helps users to store and retrieve information. To match these different situations we decided to use ZEBRA for the internal GEANFI data management and to translate and write out banks in YBOS format at the very end of the program.
The ZEBRA data structure is divided in: run initialisation banks, event banks, end-of-run banks.
The run initialisation banks are written for each run and contain information on run conditions such as detector geometry, medium, particle properties, etc. The event banks contains information on event kinematics and detector responses, finally the end-of-run banks contain general information such as run number, number of generated events, etc.
The ZTOYFI routine retrieves information from ZEBRA banks and translate them to YBOS format. It is called by UGINIT to manage the run initialisation banks and by GUOUT at the end of the event processing to manage the event banks. In addition to the previous banks two other banks are written in YBOS :LRID and EVCL. These banks are used by A_C to distinguish between different records (run record, event record).
To save disk and tape space a squeezing algorithm is applied to the YBOS banks as will be explained in the dedicated section. This reduces the data amount by 35%.
Antonella Antonelli
March 15 1997
The interactive/graphic version is a powerful tool to exploit the detector design. In this frame is possible to visualize the detector in different view, including 3-D, visualize particle trajectory and hits, retrieve bank information etc
The system is based on the KUIP command processor and uses X11 graphic interface. The main program, GXINT, takes care of graphic initialisation and KUIP menu management; a call to UGINIT routine defines the GEANFI geometry and kinematics.
After the initialisation phase the control is given to the user by the GEANT prompt, then it is possible to execute commands such as drawing, visualizing particle trajectory, etc.
The procedure to run the graphic version together with some useful command will be given in a dedicated section.
Antonella Antonelli
March 15 1997
Some subsections address general issues, like the maintenance policy, while others are more technical and they include reminders about the Data Structures, explained in the Kloe Note 137/95, a detailed description of the data cards, and of the program layout.
GEANFI contains also a part developed to simplify the production of large amounts of data, and it is ignored in the following sections. Such a part has been designed to produce the 10**8 events and it is not straightforward to use it in other cases. The documentation can be found in the dedicated part of the Kloe Offline Page.
Caterina Bloise
March 15 1997
A first document to describe the GEANFI program was written in 1993 and it is in the archive of the Kloe Notes (Kloe Note 52/93).
All further updates have been reported in the $VERSION directory available in the .CMZ file.
The present document, available on the WWW Kloe Offline Page is archived also as Kloe Memo 128/98.
We intend to update these pages following the future program developments and the user's suggestions as well.
The people to contact for any question or comment are Antonella Antonelli (Antonella.Antonelli@lnf.infn.it) and Caterina Bloise (Caterina.Bloise@lnf.infn.it).
Caterina Bloise
March 15 1997
The GEANFI code is maintained under the CMZ code management system, in the GEANFI_CMZ area at LNF. Like the rest of the Kloe Offline packages, mirrored copies are daily updated on the AFS servers both, at LNF, and at CASPUR. The policy to accede to these files is described elsewhere in the Kloe Offline Page. For each package two areas are maintained, the development and the production areas, addressed by the environmental variables set by the Kloe "setup offline'' command. At present there is some confusion in the definition of the actual reference areas, which are not always the same for all the packages. As soon as possible, to avoid any misunderstanding, the two reference areas will be unified and the "intermediate'' packages maintained elsewhere. Also the strategies to maintain the Kloe Offline packages are addressed by a dedicated document under way. Now the GEANFI reference area is the development one, pointed by the "setup GEANFI development'' command. It contains, besides the CMZ file, the fortran code pointed by the GEANFI_SRC environmental variable. In such an area the main programs for both, the batch version, and the graphic/interactive version, are stored together with the INTERFACE routine to accede to the Database. The fortran code of the GEANFI package is contained in three different files:
For each of those files the corresponding binaries for both, the graphic, and the batch versions, are in the GEANFI_EXE area.
The entire compilation procedure, including the directives to extract the fortran codes from the .CMZ file, the f77/fort77 options that must be activated, and the libraries to link with, is automatically performed by the Kloe "rebuild'' command, that accedes to the rules.mak, geanfi_package.mak, build, and post_build files to read the directives to accomplish the job. The "rebuild'' command, in the case of the GEANFI package, accepts as attributes the following keys:
At present the intermediate versions of the GEANFI program are maintained elsewhere, so that the development area contains the current version of the program.
In the GEANFI_EXE area there are also files (.CARDS) containing the whole list of the GEANFI data cards that the users can extend to include all the other data cards provided by the GEANT package. The .CARDS files at present are two, one related to the GEANFILAST code, the other one to the GEANFILASTDB/GEANFILASTFM codes. GEANFILAST does not accede to the Database and for this reason some parameters related to the detector geometry and to the detector response simulation in this version can be changed via data cards, while in the other version they are retrieved from the Database and they can not be changed any more. In the .CARDS files the input cards are generally preceded by a C and the data card name is followed by the default values of the parameters, while further lines contain a brief description of the parameter meaning. To change one of the listed parameters the user must copy the line of interest, he must cancel out the C at the beginning, and he must replace the default value with his own choice. We remind that all the lines beginning with C or * are skipped by the procedure that reads the file.
The reference area has been frequently updated and whenever the versions differed enough, the code has been frozen with its own release-number, and the update history was written in the $VERSION directory contained in the .CMZ file. The GEANFI version/release number can be read from the LRID YBOS bank (see below).
Caterina Bloise
March 15 1997
In the following the calling sequence of the GEANFI program is reported. The basic elements of the program structure are shown in turn, but the UGINIT and the GUKINE routines that are described in the Particle Generators Section below.
GEANFI
GRUN
UGLAST
Caterina Bloise
October 15 1997 .
The Data Structures and their Relationship
The YBOS montecarlo output is organized to mimic real life data structure. It contains banks relative to the detector response "raw data" in addition with montecarlo specific information. In this frame each analysis program can be applied in the same way to Montecarlo and Real Data. The full bank description can be found in the KLOE note 137. In the following we give only a short description of the data structure . The YBOS banks are divided into run initialisation, event, end-of-run banks. In the run initialisation banks particular information on the Montecarlo run conditions are stored. These quantities are usually not used for standard analysis. Their content is:
The event banks contain a lot of useful information concerning the event type and detector responses. Links between different banks are also provided to facilitate the user in the analysis stage. For each event the following banks are written:
There is one KINE bank for each particle, it contains information on the particle momenta at vertex, the energy, the mass, etc; the link to the vertex origin of the track is also provided. As well there is one VERT bank for each vertex; it contains the vertex position, the time of flight, and the links to the mother and the daughter tracks.
The "raw" banks simulate the raw data as they are coming from data acquisition. They contain information on the detector responses such as electronic address, TDC and ADC values. As for the HITS case we have one bank for each detector such as DTDR for drift chamber TDC, CTDR and CADR for calorimeter ADC and TDC, etc. At the present, the Montecarlo writes out additional banks: the so called ELEMENT banks. They are built from the "raw" banks translating digitized numbers into real numbers (from TDC to time, from ADC to charge) using calibration costants. Actually they are the input to the present reconstruction programs. Also in this case exists one bank per detector: DTCE containing time (and charge) values for drift chamber, CELE for the calorimeter time and charge values, etc.. For each of these banks exists a link bank to connect each element to the KINE track that generated it. This is only a temporary situation: in the future, raw data calibration will be done by the reconstruction programs.
The end-of-run bank (RUNG) contains general information such as run number, number of generated event, last random seeds etc.
For each record, run or event record, the LRID bank is written. It contains the information used by A_C to understand in a quick way which kind of record is dealing with. A useful keyword, EXPERIMENT TYPE, gives also immediately the Data Type, e.g. Montecarlo, test beam, Experiment Data, etc.
The ZEBRA structure is similar to the YBOS one, the only difference is in the bank format. The run initialisation banks are the same as in the YBOS case, exists only one KINE and VERT banks containing information on all the particles, the different detector responses are stored only in one HITS bank and they can be addressed using the appropriate detector name and in conclusion there is only one DIGI bank, equivalent to the YBOS "raw" bank, containing all the detector sub-systems. More information on the ZEBRA structures can be found in the GEANT manual ( [HITS] ).
Antonella Antonelli
March 15 1997
Reference System and Physical Units
This section includes both, generalities about the Master Reference and the Detector Reference Systems used by GEANT, and the numbering scheme adopted for the Kloe detectors. This last item is the focus of a dedicated document, namely the Kloe Note 115/94.
The kinematic variables of the particles transported by GEANT are always referred to the so-called MAster Reference System ( MARS). This system is implicitly defined as the local reference system of the first volume defined, which contains all the others. This is a Cartesian coordinate system with axis where .
Tracking is performed in the MARS and the input position for user routines such as the magnetic field routine is given in this system.
As explained in [GEOM001], the setup is described via the definition of an initial volume inside which all the others will be positioned. In GEANT terminology, each time a volume has contents, created either via division or by positioning other volumes inside, it is called a MOTHER. The volumes contained are called DAUGHTERs, and they, in turn, can contain volumes to a depth of 15 levels.
Each one of the daughters has its own reference system, which is referred to as the Daughter Reference System, or DRS.
The transformation of a point from the MRS to the DRS, at any level, is performed using a rotation matrix and a translation vector . The rotation matrices are computed from the spherical angles of each of the axes of the daughter reference systems ( I, II, III) with respect to the mother reference system ( 1, 2, 3). The spherical angles Theta and PHI of a direction D are defined as follows :
Examples are given in [GEOM200]. The various rotation matrices required for a given setup are defined in GEANFI during the initialisation stage.
The MOTHER volume containing all the sub-systems is ALL. Externally to this another fake volume, namely BIGB, has been defined to allow the generation of the cosmic muons. The request to show the ALL volume in the interactive version of the program causes the drawing of the entire Kloe apparatus, including the coil structure. The barrel calorimeter is described by the definition of one module and the others follow by appropriate rotations/translations. The first module is at PHI=0 and the others follow rotating anti-clockwise. The endcap calorimeters are defined starting from the description of one half of the section put at z=180 cm and then translating/rotating it to complete the entire setup. The drift chamber is defined by the external geometry only, and the wire position is considered at tracking time. The beam pipe, the quadrupole and the QCAL designs are defined in the z>0 semi-axis and then these structures are specularly reported on the other side.
Besides the convention adopted to number the volumes defined by GEANFI, we must remind that the final YBOS banks contain, for the different detectors and detector channels, the numbering scheme described in the Kloe Note 115/94.
GEANT adopts the following units throughout the program: centimeter, second, kilogauss, GeV, GeV (momentum), GeV (mass) and degree. In the YBOS banks the energies are expressed in MeV instead, and the times in nano-seconds.
Caterina Bloise
March 15 1997
The GEANFI program can be executed on both, the HP-UNIX , and the OSF platforms. Different binaries are available on the reference areas: the Kloe setup procedure recognises the platform and it defines the pointers to the corresponding area accordingly. The reference area for the executables is GEANFI_EXE, and three programs can be found there, namely gbatch.exe, gbatchdb.exe, and gbatchfm.exe, corresponding to the fortran codes described in the "Maintenance Policy" Section above.
To run the program, the file containing the data cards (an example can be found in the reference area) must be prepared and it must be assigned to the unit 17. To perform the assignment the command:
To run the gbatchdb/gbatchfm programs the CDSERV environmental variable must be defined. This variable allows to open the Kloe Database from which the programs get the apparatus and the detector parameters. The variable is set by the Kloe "setup offline" procedure, and it points to the area where the Database resides.
Because the record-length specified in the open statement is assumed to be expressed in different units on the two platforms, the third parameter in the FRMT card must properly set to avoid the wrong writing of the YBOS files. Such a parameter must be 3 in case of HP-UNIX, and 4 in case of OSF. The first two parameters in the FRMT card can be freely chosen instead. Those parameters refer to the input/output format, and whatever the choice is, the A_C readout procedure can disentangle the two formats, the HP, and the OSF one, because somewhere a bit is set to signal one format or the other.
The output with the YBOS banks is saved in the geanfio.yb file; if the Zebra output has been required, it appears in the geanfio.fz file. If those files exist in the work directory (the current directory at run time), the program aborts while attempting to open the output file, avoiding any overwriting of previous data samples. The open-failure is signalled in the log-file. We remind that to obtain the geanfio.yb file the data card YBOU 1(2) must be specified, and to obtain the ZEBRA file the SAVE card, followed by the names of the banks to save, must appear within the directive list.
Concerning the YBOS output, it is possible to assign a path different from the work directory and/or a file-name different from "geanfio.yb" by defining the environmental variable FTN102 : setenv FTN102 /.../.../.../filename .
Together with the data sample, a log file is filled during the execution, containing at the beginning general information concerning the run, such as the run number, the energy cuts used by GEANT to stop the particle tracking, and other few things described in the GEANT manual. Moreover, the events for which the tracking of one particle is not completed because the maximum number of steps is reached are reported in the file, together with the cases in which one of the detector responses falls outside the expected range. In case the card YBOU 2 is specified to obtain a squeezed set of YBOS banks, the cases in which the variables to squeeze are found outside their validity range are signalled in the log-file. At the end, the statistics of the generated events, and the average CPU-time per event are reported.
Caterina Bloise
March 15 1997
All the remarks reported in the previous section are effective in this case as well.
The reference area is pointed by GEANFI_EXE, and the names of the binary codes are gX11.exe, gX11db.exe, and gX11fm.exe, corresponding respectively to the geanfilast.f, geanfilastdb.f, and geanfilastfm.f fortran codes.
The GEANFI graphic version differs from the batch version because the main program, GXINTDB, is based on the GXINT procedure to accept the user's directives and to display the apparatus, the particle trajectory, and the position of the hit zones of the detectors.
In the present version it uses MOTIF as graphical package, and it can run on X-Window terminals.
The directives accepted by GXINT are explained in the GEANT manual. For convenience here we report the most commonly used commands:
Moreover, the DRAW command allows to obtain a 3-D picture of the apparatus /of its subsystems, the ZOOM command allows to enlarge selected zones inside the display windows, etc. All these features are described in the GEANT manual.
The interactive version, if the Zebra output was saved, can be also used to display previously generated events. To this purpose three data cards have been created:
This procedure was very useful at the beginning, before the creation of the Kloe Event Display. Today the YBOS files can be examined to some extent by the DIDONE package, described elsewhere in the WWW Kloe Offline Page.
Caterina Bloise
March 15 1997
GEANT package gives the possibility to handle general run condition using a set of data cards. This is done using FFREAD package that manages the data card definition and reads it (subroutine FFKEY and GFFGO). In the same way in GEANFI program a set of dedicated data cards are defined in the routine UDCARD. All these data cards are read at the running time, and they can be used to choose different run condition parameters from the default one. The data card format contains a key (4-character string) and a set of values; the key name helps to understand what the data card is for.
Different data card (d.c.) categories are defined:
1. The I/O control is driven by different data cards both for ZEBRA and YBOS data structure.
The ZEBRA structures, used only for debugging purposes, arenot saved by default. They can be saved using the SAVE data card and they can be retrieved by the Montecarlo using GET, FIKI and NEVE d.c..
The YBOS output is not written by default and it can be activated with the d.c. YBOU. It is also possible to select the detectors for which the HITS, RAW and ELEMENT banks are saved. This is done using the cards YBHI, YBRA and YBEL. For the HITS structure the default detector list is: Drift chamber, calorimeter, anticoincidence, quadrupoles, and quadrupole instrumentation QCAL. For the ELEMENT banks the calorimeter, the drift chamber and QCAL can be selected, while for the RAW banks at present only the calorimeter and the drift chamber output has been implemented. Following the change of the raw data structure by the Kloe Online group, also these two banks will be updated soon.
For both, the ZEBRA, and the YBOS structures it is possible to choose the output format via the FRMT data card. The default format is OSF-UNIX. In case of ZEBRA, the input format can also be chosen.
2. Physics process control
To choose between different event topology and to control physic processes, different data cards are provided. In the following these data cards are described; further information on the different generators are reported in the dedicated Section. There is the possibility to generate single particles, cosmic rays, all the phi relevant decays, Bhabha events, muon pairs and machine background. All the above processes, but the single particle case, can be generated alone or together to simulate real life. In case of simultaneous generation of different processes the relative ratio is computed assuming a machine luminosity of 5*10**32 cm-2 s-1.To change this default values the PLUP d.c. can be used. If so, all the process rates are scaled accordingly. In addition the possibility to pile-up different events is also given.
In the GEANFI program does not exist any default for the event generation, so that the user has to define the appropriate processes using the relative data cards.
The single particle generator is driven by the SPAR card where the particle type (according to GEANT number), the vertex position, and the particle momentum must be specified. Both, the vertex coordinates, and the momentum values, are extracted, following a flat distribution, within the range provided by the user.
The cosmic ray generation is driven by COSM data card. This data card has 2 keys: the first one to choose between cosmic ray generation alone or together with phi decays, and the second one to change the minimal muon momentum (0.2 GeV default value). The cosmic ray rates are calculated inside the generator taking into account of the minimal momentum and of the apparatus acceptance.
We have two Bhabha generators in GEANFI. One is the generator developed for PEP/PETRA experiment adapted for DAPHNE energies and it is described in the KLOE note 156, the second one, described in KLOE note 59/96, is more performing. It includes a better cross section description, taking into account of the radiative corrections and of the Phi contribution to the elastic cross section. The two generators are activated by BHAB and BHAN d.c. respectively. In both data cards the first key allows to generate Bhabhas alone, together with Phi decays, taking or not into account the event pile-up. The second and the third key allows to change the theta angle interval in which the events are extracted. For the BHAB case, the last two keys define the phi angle interval. For BHAN d.c., the minimal and the maximal energy fraction carried out by Bremsstrahlung photons on respect to the beam energy, and minimal value for the Hard Bremsstrahlung energy, can also be defined.
The machine background, that includes Coulomb scattering and Bremsstrahlung events, is activated by MCBK d.c. This d.c. is described by just one key to switch on/off the process or to generate it together with Phi decays. The default rates at 5*10**32 cm-2 s-1 Luminosity are 701 KHz for Coulomb scattering, and 598 KHz for Bremsstrahlung processes. It is possible to change these rates using the PLUP card. The PLUP data card is responsible for event pile-up simulation; in addition it gives also the possibility to change some default parameters, such as the Luminosity and the backgrounds rates used for simultaneous-process generation . There are 6 description keys: the first one to switch on/off the pile-up procedure (the default is no pile-up simulation), the second one to change the machine luminosity given in unit of 5*10**32 cm-2 s-1, the following three to change the background rates and the last one to change the time window in which the signal coming from different particles on the same detector element has to be integrated (default value 2 microseconds).
For the Phi generator one or all of the following channels are activated using the PHID data card:
One or more of these decay channels can be selected switching to 1 the relative flag. When more than one channel is selected, the event ratio is according to their relative branching ratio. In addition to the Phi decays mode, it is possible to select the final states for the kaons, the eta, and the rho. This is done with the data cards K0LD, K0SD for neutral kaons, KPLD, KMLD for charged kaons, ETAD and ROPD for eta and rho. The channel selection is the same as for PHID data cards and the event percentage is always according to the relative branching ratio. The decay of all the other particles involved, like pion, muon, etc, is treated by GEANT using the appropriate branching ratios and they cannot be selected.
The FSEC data card can be used to avoid the tracking of leptons, photons and hadrons in the calorimeter. This option, useful only for particular studies, allows to save disk space and CPU time. Using the same card it is also possible to store in the output only the events in which the K0l decays in the chamber and to decide which kind of particles must be saved in the KINE bank.
In addition to all these data cards GEANT provides the possibility to control particle interactions switching on/off some processes or using different packages to treat them. For examples ANNI, BREM, DRAY data cards can be used to disable Annihilation, Bremsstrahlung, Delta-Ray processes, HADR data card drives the hadronic processes, CUTS to choose the energy below which the particle are not tracked anymore, etc. Some of these data cards can be used for particular Montecarlo studies, by default all the particle process are activated in GEANT. Refer to the GEANT manual for more details [BASE,PHYS].
Before going on with d.c description, some examples for the event generation are presented.
To generate one single channel:
PHID 0 1 0 0 0 0 0 0 0 0
K0SD 1 0 0 0 0 0, or K0SD 1 1 1 1 1 1
K0LD 0 0 0 0 1 0, or K0LD 1 1 1 1 1 1
In the example above, Phi into K0l, K0s with K0l and K0s into 2 charged pions, or in everything, will be produced.
BHAN 1 ........................... will produce Bhabha events, and so on.
The above data cards used together will produce Phi and Bhabha events in the same run, without considering pile-up and using the default luminosity to calculate the Phi/Bhabha event ratio. To consider pile-up and/or to change default luminosity PLUP data card should be added:
PULP 0 2 ......... no pile-up included, default luminosity will be doubled;
PULP 1 1 ......... pile-up included, default luminosity retained.
PULP 1 2 ......... pile-up included , default luminosity will be doubled.
The same example is valid if the machine background is considered, and if you want to change its default rates.
3.and 4. Detector Geometry and General Control
The parameters to describe detector and beam pipe geometry are read out from the Database, only some of them relative to parts that are still under design, can be changed by data cards. For example, the anticoincidence detector is inserted by ANTG d.c, the lead absorbers around the beam pipe are activated by ABSI, ABSE, ABTI.
Some general data cards useful also for debugging purposes are defined by GEANT Library itself. RNDM and TRIG data cards allow to choose the starting random seed and the total number of events to generate, activating the DEBU and PRIN d.c it is possible to print out some ZEBRA banks, SWIT data cards manage the histogram booking and filling, etc.
A file containing the default values of the GEANFI data cards can be found in the reference area; for the GEANT data cards refer to the GEANT manual [BASE].
Antonella Antonelli
March 15 1997
Two kinds of output files can be saved : the usual ZEBRA file with the GEANT data structures inside, and the YBOS file, containing the data structures described in the Kloe Note 137/95. The ZEBRA files are used only for Montecarlo debugging . The two structures are compatible with two different memory-management-systems, ZEBRA and YBOS. The YBOS memory-management-system is used by the Kloe reconstruction and analysis programs, so that YBOS files are those really used for the data analysis.
The ZEBRA files and their content are fixed by the SAVE data card, followed by the names of the data structures to save.
The YBOS files are created if the YBOU 1(2) directive is given in the data cards. YBOU 2 selects squeezed banks for the output, allowing to save 35% of the disk space needed to store the "normal" banks, at a reasonable CPU-time cost.
It is possible to select to some extent the YBOS file content, by switching on/off the writing of some banks. To be schematic, we can divide the banks into four kinds:
The user can switch on/off any kind of banks, but the first one. Between the banks of each kind, the user can switch on/off the writing of the information of each subsystem of detectors, namely the drift chamber, or the barrel, or the end-cap calorimeters, or the QCAL instrumentation. The details of the data cards issuing those directives are reported in the Data Cards subsection in this chapter.
Moreover, the card FRMT(2) allows the choice between two different number representation : in one case, FRMT(2)=3, the HP-UNIX representation is chosen, in the other, FRMT(2)=4, the OSF one. The two file formats are totally equivalent as far as their readout concerns, the only drawback being the CPU-time cost of the bit-swapping procedure when the files will be read in a platform working with another type of representation. Then, if the analysis program will run mainly on a OSF platform is more convenient to choose FRMT=4, and vice versa.
Caterina Bloise
March 15 1997
As we said, the YBOS file structure corresponds to the data structure expected by the A_C program environment. It contains the LRID (Logical Record Identity) structure used by A_C to pass the program control to proper program sections.
Moreover, the data format information is contained, allowing the correct bit-swapping procedure, in case the number (integer/real) representation is different from that of the running platform. Two kinds of representations are handled by the YBOS Library. At present these are the HP-UNIX representation and the OSF one, so that whatever is the format of the Montecarlo file, the data can be read and interpreted in the correct way. It is worthwhile to outline that during 1996 the YBOS Library has been changed: the previous version, always available to maintain backward compatibility on this issue, handled the HP-UNIX and the VMS representations instead.
Then, if the analysis program is written in the A_C framework, the readout is done in a user-transparent way and the data structures can be acceded by the analysis programs calling the YBOS routines for data retrieving (BDATA, BLOCAT). No action must be taken to read those files, apart for providing the file name itself.
A little bit more complicated is the treatment of the YBOS files containing the squeezed banks : in this case a procedure is needed to have full compatibility with the analysis programs written to handle the data in the "normal" banks. At present an A_C module, namely KBKMDD, available in the K_SQZ area must be linked together with the other analysis modules to pass the "normal'' banks to the rest of the program. It is foreseen the possibility to include such a module, which accepts "normal'' banks as well, inside A_C. In this way the data access will become fully transparent for the users, also in case the "squeezed'' banks were used.
Caterina Bloise
March 15 1997
The beam energy whose central value is 510 MeV, is assumed to be gaussian-distributed, and the default value of the sigma of such a distribution is 700 KeV. The parameters can be changed by the data card BEAM. The routine PHBEAM, called by GUKINE, extracts those values.
The beams are assumed to cross each other in the horizontal plane, and their crossing angle is 12.5 milliradians. This is taken into account to compute the Phi kinematics, the Bhabha kinematics, and the muon-pair events.
The beam dimensions are 3 cm in the z-direction, 0.211 cm in the x-direction, and 0.00211 cm in the y-direction. The crossing point coordinates are assumed to be gaussian-distributed and the sigmas are those reported above divided by SQRT(2). The routine PHVERT, called by GUKINE, extracts the primary vertex for the Phi decay events, the Bhabha events and the muon-pair events. Those parameters can be also changed, by the data card SRCE.
The description of the interaction zone includes the beam pipe detailed design extending along 5 m, and the design of the six focusing quadrupoles. For the quadrupoles, the shapes, the materials and the magnetic field are implemented. The beam pipe is constituted by different sections:
Such a description is provided by the UDPIPE routine, called by UGINIT at initialisation time.
The quadrupoles are defined in the UDQUAG subroutine. Three different pairs of quadrupoles have been designed, having XY circular sections whose radii change along Z, and a total thickness respectively of 2.6, 6.6, and 3.65 cm. The material components change with the radius: two parts have been envisaged, the most internal one is in a Sm-Co league, and the external one, about 1.3 cm thick, in Aluminum.
The description of the magnetic field inside the quadrupoles is provided in the GUFLD routine and it is of interest especially for the tracking of the Bhabha events (and their secondaries) at low angle, and for the machine-background particles.
Caterina Bloise
March 15 1997
For completeness we describe here the UGINIT and the GUKINE codes, that include the calling sequences to initialise and to execute the generator procedures.
The calls to initialise the generators are issued if the relative flags in the data-cards are set.
Some of the GUKINE calls are exclusive, e.g. once a call has been done the following are skipped; we have denoted them with "exclusive" hereafter.
UGINIT
GUKINE
Caterina Bloise
March 15 1997
In this section a description of phi generator together with list of routines involved is given. As already mentioned GEANFI can handle the following phi decay channels:
Phi decays channels are driven by PHPHID subroutine called by GUKINE event by event. In this routine according to the PHID data card one or more Phi channels can be selected.
The decay into neutral and charged kaons is driven by PH2BOD routine that generates the event in the center of mass (c.o.m.) frame using a sin**2(theta) distribution. A Lorenz-boost is then applied to the particle momenta to report them to the Laboratory system by a call to LORBCK routine. The K0s decay modes include 2-pions, semileptonic finale states, pai+pai-photon, 3pai0s, and the photon-photon channels. They are defined in the routine UGINIT at the initialisation phase. As already mentioned, each mode can be selected exclusively or produced according to their relative branching ratio (B.R.) using K0SD data card.
For the K0l decay modes, the 3-pions, the semileptonic, the CP violating, and the pai+pai-photon channels are considered. The mode definition is done by PHK0LD routine, called by PHPHID event by event ( GEANT does not allow the definition of more than six decay channels ). Each mode can be selected by K0LD data card.
The charged-kaon decays include muon neutrino, 2-pions, 3-pions and the semileptonic modes, and they can be chosen by the KPLD/KMLD data cards.
The 2(3) body kaon decays, but the semileptonic, the pai+pai-pai0, and the pai+pai-photon ones, are generated according to an isotropic angular distribution in the c.o.m. system by means of GDECA2(GDECA3) routine called by GEANT at the tracking time.
To take into account of the V-A structure of the kaon semileptonic channels, the GDECA3 subroutine has been modified including the decay matrix element. The decay amplitude is function of two relevant parameters, the form factors lambda+ and lambda0, and their values are taken from the Particle Data Group book.
The Klong/Kshort decays into pai+pai-pai0 are generated according to the matrix element by a call to PPM0SD/PPM0LD routine inserted in the GDECA3 subprogram. The phase-space distribution can be found in the Second Daphne Physic Handbook, Vol I, p.239, in a review article written by L.Maiani and N. Paver.
The decays into pai+pai-photon are treated analogously to the pai+pai-pai0 channel, by calling from GDECA3 the PIPIGI routine, for the internal bremsstrahlung process (see D'Ambrosio et al., Second Daphne Physic Handbook, Vol I, p.79), and the PIPIGD routine for the direct decays (see E.J. Ramberg et al., Phys. Rev. Lett. 70 (1993) p.2525).
Finally, the quantum mechanic interference pattern between K0l-K0s decays is also taken into account; this is done in GUSTEP by a call to the routine QMINTP. The 2-pions and the semileptonic final states are considered, and a weight equal to the event probability is written in the HEAD bank.
The Phi--> rho-pion decay is generated according to an isotropic distribution in the c.o.m. system for the 2-pions-photon and the eta-photon final states, while for the 2-charged-pions-neutral-pion mode the decay matrix element described in Phys. Lett. 3B(1976)362 has been taken into account (subroutine RHODM).
The Phi--> eta-photon, the eta'-photon and the pion-photon channels are generated according to cos**2(theta) distribution in the c.o.m. system. The eta decays are in turn treated by the subroutine ETADEC, where the 3-pions and the 2-pions-photon decay modes are simulated using Dalitz plot distributions (Phys. Rev. D 7(1973)2565, Phys. Rev. D 2 (1970)501).
To simulate the Phi--> f0-photon and its related background, a dedicated generator has been developed. The signal amplitude is expressed in terms of photon energy and photon angular distribution as reported in "The DAPHNE Physics Handbook" (volume II pag. 513); moreover the interference term between Phi -->f0-photon-->2-charged-pions-photon amplitude and the direct channel Phi--> 2-charged-pions-photon amplitude is taken into account to evaluate the total process. The relative amplitude sign is not yet measured, so that in the simulation it is possible to choose between constructive and destructive intererfence using PHID data card. The background processes (Phi--> 2-neutral-pions-photon, and Phi-->2-charged-pions-photon) are described using VDM model and Chiral perturbation theory; for the last channel the initial and the final state radiation amplitudes are also calculated.The F0BK data cards can be used to choose the model with which the background is described (by default VDM and Chiral theory is used). This generator is driven by the subroutine PHF0D(n), where n=1 for constructive interference, and n=0 for the destructive case. The PHIF0 routine calculates the signal amplitude; the interference term is calculated in PHIIN, and the total amplitude in MTXBKG. The background processes are treated in PH2P0G and PH2PCG routines for the 2-neutral-pions-photon and the 2-charged-pions-photon channels respectively.
All the other unstable particles are treated by GEANT using GDECA3 or GDECA2 routines according to pure phase space.
Antonella Antonelli
March 15 1997
The cosmic ray generator is described in the Kloe note 57/93. The generator is activated by COSM data card where the minimal muon momentum can be chosen (the default values is 0.2 GeV), as well as the minimal zenithal angle to be accounted for. The muon momentum and direction are generated according to the Dar parameterisation that gives spectral muon intensity as a function of the zenith angle (theta) and of the particle momentum. The muon vertex is generated on a spherical surface surrounding the Kloe iron yoke, taking into account of the muon intensity as a function of the muon direction.
The cosmic generation is driven by the MUONIN and GENEMU routines.
MUONIN is called at the initialisation time by UGINIT, it contains the tables of numeric integration of the Dar distribution. The spectral intensity, integrated over the angle using a 0.001 cos(theta) bin, is given for 22 momentum values (from 0.2 up 1000 MeV). Moreover it calculates the total muon flux on the spherical surface (478 cm radius) according to the minimal muon momentum defined in the COSM data card (default value 0.2 GeV).
GENEMU is called by GUKINE event by event to define the muon kinematics. The first step is to extract the muon momentum according to spectral intensity integrated over the solid angle. Once the momentum is fixed, the direction is generated using the function DARDIS that calculates the differential distribution for the given momentum value. The last step is the vertex generation on the spherical surface; this simulation takes into account that the muons illuminate the sphere from all directions with an intensity that is function of their direction.
The momentum components and the vertex coordinates are then stored in the KINE and VERT banks.
Antonella Antonelli
March 15 1997
The description of the calculation performed by this generator can be found in the Kloe-Memo 59/96. The generator includes the radiative soft corrections (alfa order) to the electron-positron elastic scattering, taking into account of the phi-resonance too, and the "Hard Bremsstrahlung" processes. Here the program flow is reported.
The Bhabha generation is driven by the EGENER(n) routine : it is called by UGINIT (EGENER(-1)) and by GUKINE (EGENER(0)).
EGENER(n)
The first call to the BHABHA subroutine causes the computation of the lowest order cross section, of the cross section of the soft-photon Bremsstrahlung, of the hard-photon Bremsstrahlung, of the approximate total cross section, and of the foreseen correction to this cross section. All those quantities depend on the parameters given by the data-card BHABHN, namely, the minimal (maximal) scattering angle of the electron in the c.o.m. system, and the minimal (maximal) percentage of the beam energy requested to consider the photon as an "Hard-Bremsstrahlung-photon".
The default values are : 1-179 degrees for the scattering angles, and 0.01-1. for the beam-energy percentage of the "hard" photons.
The beam energy, the minimum and the maximum of the scattering angle, the minimum and the maximum of the hard Bremsstrahlung energy, the lowest order cross section, the approximate cross section for the soft Bremsstrahlung processes and for the hard ones, the approximate total cross section, and the total amount of the foreseen correction, are printed in the log-file by the first call to the BHABHA routine.
The further calls to the BHABHA routine causes instead the following actions:
All the kinematic variables sorted by the BHABHA routine are scaled for the beam energy in the c.o.m. frame. EGENER performs the final computation of the 4-momentum components.
Caterina Bloise
March 15 1997
As it has been explained in the Introduction, the GEANFI program provides the kinematics of the particles leaving the beam pipe in the Kloe interaction region. Those particles, due to the high luminosity of the machine, have an extremely high rate and they must be filtered out by the triggering system. To accomplish this kind of studies, a parameterisation of the relevant features of those particles has been done by Vincenzo Patera, starting, as we mentioned before, from the results of the simulation of the particle transport throughout the Daphne magnets provided by the TURTLE program.
The most dangerous background is constituted by the electrons (positrons) undergoing Coulomb scattering and electrons (positrons) plus photons generated by Bremsstrahlung processes. At the energies of interest the Coulomb particles are foreseen to reach a rate of 700 KHz, and those coming from Bremsstrahlung a rate of 600 KHz in the interaction region, at a Daphne Luminosity of 5*10**32 cm-2 s-1.
The generation is driven by the MCBK data card, related to 2 parameters, the first is the usual flag used to switch on/off the procedure (flag=1/0) or to activate the procedure together with Phi decays (flag=2), the second to modify, when the flag is 2, the machine background ratio to the Phi decays on respect the expected one at the specified luminosity.
In the case of mixed generation (flag=2), it is possible to change the relative amount of Bremssthralung/Coulomb scattering by the PLUP data-card. In this case the third and the fourth parameter allow to set independently the rate of the two kinds of background, while the second parameter modifies the machine luminosity value.
Starting from the next GEANFI release v1.06/02, using the MCBK data card (first key = 3), it will be possible to generate the machine background particles directly using the TURTLE code. Such a procedure, more CPU-expensive, allows a detailed study of the trigger response including those event topologies discarded by the parameterization being too rare, but that neverthless can represent a sizeable amount of all the machine-background triggers mimicking the ``Phi" event topologies. The TURTLE procedure is initialised by a call to TSETUP from UGINIT and then is called by GUKINE, according to the MCBK data card, by a call to RAYRUN. TSETUP fills all the required variables related to the DAPHNE magnetic layout, and RAYRUN generates the bremsstrahlung and the Coulomb-scattering processes, selecting those particles exiting from the beam pipe in the KLOE interaction region afterward.
C. Bloise
December 15 1997
The muon pairs are generated by the MUPAIR routine called by UGINIT to compute the total cross section according to the minimal/maximal zenith angles specified in the data card MUMU (default are 10 and 170 degrees). The total cross section is used to calculate the relative amount of events if other generators are activated at execution time. It is possible to change the normal ratio by the MUMU data card (fourth parameter, default is 1). MUPAIR is then called by UGINIT to compute the muon kinematics and their primary vertex. The differential cross section used is:
5.18 nbarn/ s (GeV**2) * betamu * ( 2 - betamu**2 + betamu**2 * costheta**2 ),
where s is the center-of-mass energy squared, betamu is the muon velocity in c units, and costheta is the cosine of the muon zenithal angle.
C. Bloise
October 15 1997
Geanfi can generate single particles in the initial position and with the momentum specified in the data card SPAR. If the card is activated, SINPGE is called by GUKINE to generate the momentum and the primary vertex of the selected particle, according to the boundaries provided by the data cards. The particle type is fixed, and it is read by the data cards too. The order of the parameters in the data cards are the following:
1. particle type (fixed) (GEANT code - see GEANT manual -);
2. distance of the primary vertex position from the center of the
Kloe setup (fixed);
3,4. boundaries (min and max values) of the primary vertex position
along Z-axis;
5,6. boundaries (min and max values) of the azimuthal angle of the
primary vertex position;
7,8. boundaries (min and max values) of the particle momentum;
9,10. boundaries (min and max values) of the cosine of the momentum
zenithal direction;
11,12. boundaries (min and max values) of the momentum azimuthal
direction.
C. Bloise
October 15 1997
A brief description of the Drift Chamber, the Calorimeters, and the quadrupole instrumentation QCAL is given hereafter.
The Drift chamber simulation contains: a detailed description of the chamber geometry, a dedicated tracking that takes into account of the interaction of the particles with the chamber gas and wires, and a careful simulation of the detector signal.
The chamber geometry, defined in the routine UDTCG, consists of :
The chamber is filled with a gas mixture 90% He +10% Isobutane.
There are actually 58 layers, the first 12 containing 2x2 cm2 cells, and the remaining having 3x3 cm2 cells. The field to sense wire ratio is 3:1. The wire material is Aluminum for the field wires and Tungsten for the sense wires, with a diameter respectively of 80 and 25 microns.
All the parameters used to describe the chamber geometry are stored in the Database.
To avoid a big increase of the CPU time needed to generate the events, the chamber wires are not explicitly described in the GEANT geometry, and to take into account of their contribution to the multiple scattering a dedicated procedure is activated at the tracking time.
A package, driven by the subroutine TRACCE, has been written to track the particles in the chamber. In this scheme the particles stored in the GEANT banks are tracked traditionally until they reach the chamber gas, where the dedicated tracking package takes control. When the tracks leave the chamber the normal tracking is restored. This package uses standard GEANT routines for tracking (GUSWIM) and for particle interaction in the corresponding medium.
The cell geometry is calculated for each tracking step using the wire position and the stereo angle stored in the Database. In case a particle hits a wire, the multiple scattering, using the appropriate wire material, is performed, and also the energy loss in the cell is computed..
For each crossed cell the program computes the distances of closest approach between the track helix and the nearest sense wire. This distances are converted to drift times by using the proper space-to-time relations. More details on this package and on the space-to-time relations can be found in "THE KLOE CENTRAL DRIFT CHAMBER" (LNF-94/028).
The information about the hit cells is written into 2 output banks, DHIT and DTCE.
DHIT contains information useful for debugging purposes such as the particle that generated the hit (momentum, particle type, etc.), and on the cell response (cell address, drift distance, drift time, etc.). In case of multihit in the same cell all the hits are present in the bank.
DTCE is the bank obtained by the raw data calibration and it contains the cell address, the time (and the charge). Only the hit with the minimal time is retained if the same cell is hit more than one time. This bank is actually the input to the pattern recognition program. The time in DTCE as well as the TDC values in DTDR (see below) is the sum of:
drift time + particle time of flight + wire propagation time
The wire propagation time is computed assuming a propagation speed of 0.035 ns/m, and the wire readout is done at +z for the odd layers, and at -z for the even ones.
The raw banks DTDR (and DADR), containing the TDC (and ADC) counts respectively, are also filled, but they are not generally written out, due to the fact that the present Montecarlo version does not contain any calibration inside.
Also in these banks only the hit with the minimal time is retained if the same cell is hit more than one time.
Antonella Antonelli
March 15 1997
The calorimeters are described in the UDCALG and in the UDECNG routines, for the Barrel and the Endcaps, respectively. The Barrel is defined by a an external Aluminum container whose dimensions match one Kloe Barrel Module. Inside the Aluminum are placed horizontal, alternate, planes of lead and plastic scintillators. The planes cover a total thickness of 23 cm, corresponding to 15 X0s, and each lead layer is 0.07 cm, while the scintillator planes are 0.014 cm thick. Such a structure brings with it a sampling fraction for the electromagnetic showers of interest of 15%, while the Kloe calorimeter done by scintillating fibers interleaved by hollow lead sheets, has been measured to have a sampling fraction of 13%. The difference has been absorbed in the digitalization procedure, modifying accordingly the number of photons/MeV simulated for the final response.
The difference in the detector responses due to showers and to minimum ionizing particles are reproduced at present within 15%. We plan to update this point soon, using the cosmic muon data set to establish the right ratio. Comparing the real and the Montecarlo released-energy-distributions for cosmic muons, the correction comes out to be -15% per cent of the simulated value.
The Endcap design has been done by using different volumes, for the vertical, straight part of each Module, for the curve section, and again for the horizontal, straight end of each wedge. Each Module, besides the detailed shape, is described analogously to the Barrel, e.g. by interleaving lead and scintillator plates of the same thickness cited before.
The energy loss in each scintillator plane and the crossing time are used by the digitization procedure to simulate the ADC values. The criteria of such a procedure have been described in The Detector Response Simulation Section above. At present the element banks are filled with the yet calibrated quantities, e.g. the MeV and the ns for each hit calorimeter element.
The values match very well the measured calorimeter response for the electromagnetic showers, and the simulation provides the right energy and time resolutions, in the whole energy range of interest for Kloe.
The digitalisation is driven by UDIGIC, called by GUDIGI, and the final values are then revised to create the final output by the ZTOYCE routine.
C. Bloise
August 15 1997
I provided the basics for the geometrical description and the response simulation of the QCAL calorimeters. The design has been further developed by Corti in June 1997, who revised also the simulation of the detector response, taking into account of the measurements done on the detector prototypes. Santovetti revised later this part of the code, available in its final version in the v1.06/01 GEANFI release. The code, as usual, consists of three parts, one routine, UDINQG, providing the geometrical description of the detector, another one, UDIGIQ, simulating the detector response, and the third, ZTOYI, devoted to create the data structures.
The QCAL calorimeters surround the three focusing quadrupoles in the Kloe interaction region, and their main purpose is to detect the photons impinging the quadrupoles. It is done by lead and scintillating fibers and it is read by wave-shifter-fibers running along the 80 cm detector length, that are properly grouped to obtain the sixteen azimuthal channels on each calorimeter. Each phototube collects photons coming from two modules, the direct one and the second-next-module, by an additional piece of fiber connecting each module with the second-next neighbour. These details are plenty described, together with the calorimeter shape, enlarging the radius along Z to surround the quadrupoles, from the interior outwards.
C. Bloise
August 15 1997
In this chapter the content of the YBOS banks is reported, together with the criteria and the parameters currently used to pack the Montecarlo banks. The content and the bank structure is the same for the packed as well as for the ``normal" banks, the name of the packed banks is the same, but lower-case letters are used instead of the capital-case letters used for the ``normal " banks.
The banks that are not packed, namely the KINE bank, the EVCL, the HEAD, the RUNG and the initialisation banks, can be found in the KLOE Note 137/95.
As explained before, the YBOS banks are filled by the ZTOYFI procedure starting from the GEANT-native ZEBRA banks whose structure is reported in the previous GEANFI document (Kloe Note 52/93). Those structures, being currently used mainly as GEANFI-internal data storage locations, are not included here. Neverthless, by request, we can enlarge the present description with the list and the content of the ZEBRA banks.
C. Bloise
December 15 1997
In order to save space in case of large event productions, a procedure translated also in an A_C module, namely KBKMDE, has been created to squeeze the Montecarlo banks.
The greatest majority of the Montecarlo banks have been considered in this work, resulting in a 35% of space-saving. Few banks remain in the usual form because their structure is packed enough to avoid any further reduction following the adopted criteria.
To distinguish between unsqueezed/squezeed data, the convention to use upper-case names for the usual banks and the same, but lower-case names for the compressed ones, has been adopted.
At BEGIN RUN few additional banks appear onto the output file when the "squeezed" format is chosen, passing the data card value YBOU 2. For each packed bank one additional bank is provided at BEGIN RUN containing the parameters needed to perform the further bank unpacking. These additional banks have the same name as the original banks have, but lower case is used instead, and the fourth character is replaced by I (infos).
The encoding procedure, as it is now, can handle different kinds of data structures. It assumes that the data words can be logically divided into an header plus a variable number of data blocks. Each data block can be composed by a fixed number of data words plus a certain number of sub-blocks of variable length. Each variable length sub-block starts with a word containing the number of sub-blocks that must be stored. Banks can be composed by any combination of these sections, so that it is possible to handle fixed-length banks as well as banks composed only by variable-length sections.
The data words are translated into positive numbers (at present 32-bits words are used) according to the offsets and the scale factors declared and stored in the ***I bank. These positive integers are packed together according to the number of bits needed to represent them till 32-bits are reached. If the number of bits needed for the n-th data word can not be entirely housed in the packed word, a new word is used. Such a prescription allows to simplify the encoding and the decoding procedures because any data word is completely represented by only one packed word. A further division of the packed words is done between the different sections of the data structure, so that a new packed word starts when the header has been completed and whenever a new block or sub-block starts. This prescription allows to maintain the packing optimization established for the data structure, whatever bank length is. I tried also to run the code without this last prescription and, as it was expected, the output size increases.
The final result of the encoding procedure is the reduction of the Montecarlo output by 35%, previous 25Kbytes per event being now 16Kbytes on average.
The additional CPU needed to decode/encode the packed banks is almost equal to the CPU needed to read and write the events, e.g. 6 ms per event on an ALPHA-DEC3000/900, having a CPU power of about 200 SpecInt92. The quoted numbers refer to a data set of 5,000 neutral kaon pairs decaying following natural branching ratios.
In the following the entire set of the banks containing the information necessary to squeeze/unsqueeze the data will be reported for reference.
The verI bank contains offsets, scale factors and number of bits needed to encode/decode the VERT bank. This is the Montecarlo bank with the positions of any primary/decay vertex in the event. While the VERT bank number corresponds to the sequential, increasing number of vertice, the verI bank number is the bank version and it refers to the different bank structure versions. All the infos, like the length of the header, the length of the words per block, etc. refer to the vert bank, e.g. to the packed version of the VERT bank.
YBOS Bank header:
-----------------
Bank Name: verI
Bank Number: 1 (or current VERT bank version)
Bank Data Length: 35
Bank Type: Mixed
The Bank contains the following information:
-------------------------------------------------------------------
offset word type description
-------------------------------------------------------------------
0 I*4 Header length (words in the vert bank) = IHEA=0
1 I*4 Infos per block - fixed part (f.p.) = NFI=6
2 I*4 Number of blocks of variable length = NVB=2
3:4 I*4 Infos per sub-block - variable-length parts (v.p.)
-------------------------------------------------------------------
5 I*4 Number of bits used to encode first info word (f.p.)
...
10 I*4 Number of bits used to encode last info word (f.p.)
-------------------------------------------------------------------
11 I*4 Number of bits used to encode number of words
of the first sub-block (v.p.)
-------------------------------------------------------------------
12 I*4 Number of bits used to encode info word of the
first sub-block (v.p.)
-------------------------------------------------------------------
13 I*4 Number of bits used to encode number of words of the last
sub-block (v.p.)
-------------------------------------------------------------------
14 I*4 Number of bits used to encode info word of the
last sub-block (v.p.)
-------------------------------------------------------------------
15 R*4 Offset to encode first info word (f.p.)
...
20 R*4 Offset to encode last info word (f.p.)
-------------------------------------------------------------------
21 R*4 Offset to encode number of words of the first
sub-block (v.p.)
-------------------------------------------------------------------
22 R*4 Offset to encode info word of the
first sub-block (v.p.)
-------------------------------------------------------------------
23 R*4 Offset to encode number of words of the last
sub-block (v.p.)
-------------------------------------------------------------------
24 R*4 Offset to encode info word of the
last sub-block (v.p.)
-------------------------------------------------------------------
25 R*4 Scale factor to encode first info word (f.p.)
...
30 R*4 Scale factor to encode last info word (f.p.)
-------------------------------------------------------------------
31 R*4 Scale factor to encode number of words of the first
sub-block (v.p.)
-------------------------------------------------------------------
32 R*4 Scale factor to encode info word of the
first sub-block (v.p.)
-------------------------------------------------------------------
33 R*4 Scale factor to encode number of words of the last
sub-block (v.p.)
-------------------------------------------------------------------
34 R*4 Scale to encode info word of the
last sub-block (v.p.)
-------------------------------------------------------------------
The dihI Bank contains offsets, scale factors and number of bits needed to encode/decode the DHIT bank. This is the Montecarlo bank with the information of the particle tracking inside the drift chamber.
YBOS Bank header: Bank Name: dihI Bank Number: 1 (or current DHIT bank version) Bank Data Length: 51 Bank Type: Mixed
The Bank contains the following information:
-------------------------------------------------------------------
offset word type description
-------------------------------------------------------------------
0 I*4 Header length (words in the vert bank) = IHEA=1
1 I*4 Infos per block (f.p.) = NFI=15
2 I*4 Number of blocks of variable length = NVB=0
-------------------------------------------------------------------
3 I*4 Number of bits used to encode the header word
-------------------------------------------------------------------
4 I*4 Number of bits used to encode first info word
...
18 I*4 Number of bits used to encode last info word (f.p.)
-------------------------------------------------------------------
19 R*4 Offset to encode the header word
-------------------------------------------------------------------
20 R*4 Offset to encode first info word (f.p.)
...
34 R*4 Offset to encode last info word (f.p.)
-------------------------------------------------------------------
35 R*4 Scale factor to encode the header word
-------------------------------------------------------------------
36 R*4 Scale factor to encode first info word (f.p.)
...
50 R*4 Scale factor to encode last info word (f.p.)
-------------------------------------------------------------------
The cihI Bank contains offsets, scale factors and number of bits needed to encode/decode the CHIT bank. This is the Montecarlo bank with the information of the particle tracking inside the calorimeters.
YBOS Bank header:
-----------------
Bank Name: chiI
Bank Number: 1 (or current CHIT bank version)
Bank Data Length: 33
Bank Type: Mixed
The Bank contains the following information:
-------------------------------------------------------------------
offset word type description
-------------------------------------------------------------------
0 I*4 Header length (words in the vert bank) = IHEA=1
1 I*4 Infos per block (f.p.) = NFI=9
2 I*4 Number of blocks of variable length = NVB=0
-------------------------------------------------------------------
3 I*4 Number of bits used to encode the header word
-------------------------------------------------------------------
4 I*4 Number of bits used to encode first info word
...
12 I*4 Number of bits used to encode last info word (f.p.)
-------------------------------------------------------------------
13 R*4 Offset to encode the header word
-------------------------------------------------------------------
14 R*4 Offset to encode first info word (f.p.)
...
22 R*4 Offset to encode last info word (f.p.)
-------------------------------------------------------------------
23 R*4 Scale factor to encode the header word
-------------------------------------------------------------------
24 R*4 Scale factor to encode first info word (f.p.)
...
32 R*4 Scale factor to encode last info word (f.p.)
-------------------------------------------------------------------
The cfhI Bank contains offsets, scale factors and number of bits needed to encode/decode the CFHI bank. This is the Montecarlo bank with the information of the neutral particle impinging the calorimeters and of their conversion points.
YBOS Bank header:
-----------------
Bank Name: cfhI
Bank Number: 1 (or current CFHI bank version)
Bank Data Length: 39
Bank Type: Mixed
The Bank contains the following information:
-------------------------------------------------------------------
offset word type description
-------------------------------------------------------------------
0 I*4 Header length (words in the vert bank) = IHEA=1
1 I*4 Infos per block (f.p.) = NFI=11
2 I*4 Number of blocks of variable length = NVB=0
-------------------------------------------------------------------
3 I*4 Number of bits used to encode the header word
-------------------------------------------------------------------
4 I*4 Number of bits used to encode first info word
...
14 I*4 Number of bits used to encode last info word (f.p.)
-------------------------------------------------------------------
15 R*4 Offset to encode the header word
-------------------------------------------------------------------
16 R*4 Offset to encode first info word (f.p.)
...
26 R*4 Offset to encode last info word (f.p.)
-------------------------------------------------------------------
27 R*4 Scale factor to encode the header word
-------------------------------------------------------------------
28 R*4 Scale factor to encode first info word (f.p.)
...
38 R*4 Scale factor to encode last info word (f.p.)
-------------------------------------------------------------------
The qhiI, ahiI and qihI banks contain offsets, scale factors and number of bits needed to encode/decode the QHIT, AHIT and QIHI banks. These are the Montecarlo banks with the information of the particle tracking inside the quadrupoles, the anticoincidence devices and the quadrupole instrumention QCAL.
YBOS Bank header:
-----------------
Bank Name: qhiI
Bank Number: 1 (or current QHIT bank version)
Bank Data Length: 42
Bank Type: Mixed
The Bank contains the following information:
-------------------------------------------------------------------
offset word type description
-------------------------------------------------------------------
0 I*4 Header length (words in the vert bank) = IHEA=1
1 I*4 Infos per block (f.p.) = NFI=12
2 I*4 Number of blocks of variable length = NVB=0
-------------------------------------------------------------------
3 I*4 Number of bits used to encode the header word
-------------------------------------------------------------------
4 I*4 Number of bits used to encode first info word
...
15 I*4 Number of bits used to encode last info word (f.p.)
-------------------------------------------------------------------
16 R*4 Offset to encode the header word
-------------------------------------------------------------------
17 R*4 Offset to encode first info word (f.p.)
...
28 R*4 Offset to encode last info word (f.p.)
-------------------------------------------------------------------
29 R*4 Scale factor to encode the header word
-------------------------------------------------------------------
30 R*4 Scale factor to encode first info word (f.p.)
...
41 R*4 Scale factor to encode last info word (f.p.)
-------------------------------------------------------------------
Identical structures are used for ahiI and qihI banks.
The dtcI Bank contains offsets, scale factors and number of bits needed to encode/decode the DTCE bank. This is the bank with the calibrated drift chamber measurements.
YBOS Bank header:
-----------------
Bank Name: dtcI
Bank Number: 1 (or current DTCE bank version)
Bank Data Length: 15
Bank Type: Mixed
The Bank contains the following information:
-------------------------------------------------------------------
offset word type description
-------------------------------------------------------------------
0 I*4 Header length (words in the vert bank) = IHEA=1
1 I*4 Infos per block (f.p.) = NFI=3
2 I*4 Number of blocks of variable length = NVB=0
-------------------------------------------------------------------
3 I*4 Number of bits used to encode the header word
-------------------------------------------------------------------
4 I*4 Number of bits used to encode first info word
...
6 I*4 Number of bits used to encode last info word (f.p.)
-------------------------------------------------------------------
7 R*4 Offset to encode the header word
-------------------------------------------------------------------
8 R*4 Offset to encode first info word (f.p.)
...
10 R*4 Offset to encode last info word (f.p.)
-------------------------------------------------------------------
11 R*4 Scale factor to encode the header word
-------------------------------------------------------------------
12 R*4 Scale factor to encode first info word (f.p.)
...
14 R*4 Scale factor to encode last info word (f.p.)
-------------------------------------------------------------------
The dtkI/cekI Bank contains offsets, scale factors and number of bits needed to encode/decode the DTKA/CEKA bank. These are the banks with the pointers to the KINE bank for any block in the DTCE/CELE bank.
YBOS Bank header:
-----------------
Bank Name: dtkI
Bank Number: 1 (or current DTKA bank version)
Bank Data Length: 13
Bank Type: Mixed
-------------------------------------------------------------------
offset word type description
-------------------------------------------------------------------
0 I*4 Header length (words in the vert bank) = IHEA=1
1 I*4 Infos per block (f.p.) = NFI=0
2 I*4 Number of blocks of variable length = NVB=1
3 I*4 Number of infos in the variable-length sub-block
-------------------------------------------------------------------
4 I*4 Number of bits used to encode the header word
-------------------------------------------------------------------
5 I*4 Number of bits used to encode number of words of the
sub-block (v.p.)
-------------------------------------------------------------------
6 I*4 Number of bits used to encode info word of the
sub-block (v.p.)
-------------------------------------------------------------------
7 R*4 Offset to encode the header word
-------------------------------------------------------------------
8 R*4 Offset to encode number of words of the
sub-block (v.p.)
-------------------------------------------------------------------
9 R*4 Offset to encode info word of the
sub-block (v.p.)
-------------------------------------------------------------------
10 R*4 Scale factor to encode the header word
-------------------------------------------------------------------
11 R*4 Scale factor to encode number of words of the
sub-block (v.p.)
-------------------------------------------------------------------
12 R*4 Scale factor to encode info word of the
sub-block (v.p.)
-------------------------------------------------------------------
An identical structure is used for cekI bank.
The dthI Bank contains offsets, scale factors and number of bits needed to encode/decode the DTHA bank. This is the bank with the pointers to the DHIT bank for any block in the DTCE bank.
YBOS Bank header:
-----------------
Bank Name: dthI
Bank Number: 1 (or current DTHA bank version)
Bank Data Length: 10
Bank Type: Mixed
The Bank contains the following information:
-------------------------------------------------------------------
offset word type description
-------------------------------------------------------------------
0 I*4 Header length (words in the vert bank) = IHEA=0
1 I*4 Infos per block (f.p.) = NFI=0
2 I*4 Number of blocks of variable length = NVB=1
3 I*4 Number of infos in the variable-length sub-block
-------------------------------------------------------------------
4 I*4 Number of bits used to encode number of words of the
sub-block (v.p.)
-------------------------------------------------------------------
5 I*4 Number of bits used to encode info word of the
sub-block (v.p.)
-------------------------------------------------------------------
6 R*4 Offset to encode number of words of the
sub-block (v.p.)
-------------------------------------------------------------------
7 R*4 Offset to encode info word of the
sub-block (v.p.)
-------------------------------------------------------------------
8 R*4 Scale factor to encode info word of the
sub-block (v.p.)
-------------------------------------------------------------------
9 R*4 Scale factor to encode info word of the
sub-block (v.p.)
-------------------------------------------------------------------
The celI Bank contains offsets, scale factors and number of bits needed to encode/decode the CELE bank. This is the bank with the calibrated calorimeter measurements.
YBOS Bank header:
-----------------
Bank Name: celI
Bank Number: 1 (or current CELE bank version)
Bank Data Length: 24
Bank Type: Mixed
The Bank contains the following information:
-------------------------------------------------------------------
offset word type description
-------------------------------------------------------------------
0 I*4 Header length (words in the vert bank) = IHEA=2
1 I*4 Infos per block (f.p.) = NFI=5
2 I*4 Number of blocks of variable length = NVB=0
-------------------------------------------------------------------
3 I*4 Number of bits used to encode first header word
4 I*4 Number of bits used to encode last header word
-------------------------------------------------------------------
5 I*4 Number of bits used to encode first info word
...
9 I*4 Number of bits used to encode last info word (f.p.)
-------------------------------------------------------------------
10 R*4 Offset to encode first header word
11 R*4 Offset to encode last header word
-------------------------------------------------------------------
12 R*4 Offset to encode first info word (f.p.)
...
16 R*4 Offset to encode last info word (f.p.)
-------------------------------------------------------------------
17 R*4 Scale factor to encode first header word
18 R*4 Scale factor to encode last header word
-------------------------------------------------------------------
19 R*4 Scale factor to encode first info word (f.p.)
...
23 R*4 Scale factor to encode last info word (f.p.)
-------------------------------------------------------------------
In the following I will report the YBOS banks that have been included in the PACKINF routine so far. PACKINF collects the information needed to create the packed, lower case banks and it is called at BEGIN RUN to create the corresponding ***I structures.
At present, twelve banks are included in the list. The structure of the corresponding, upper-case banks together with the offsets, the scale factors and the number of bits per word needed to encode them, are presented below.
There are as many VERT banks as vertices in the event; the number of the VERT bank is the same as the vertex number given by GEANT. Each bank contains the following information:
YBOS Bank header:
-----------------
Bank Name: VERT
Bank Number: Vertex number
Bank Data Length:
Bank Type: BNKTR4 ! R*4
Each word in the bank can be located through the offsets shown below.
-------------------------------------------------------------------
offset word type description enc. offsets scales bits
-------------------------------------------------------------------
VERXCO R*4 X coordinate of the vertex. 500 10**6 32
VERYCO R*4 Y coordinate of the vertex. 500 10**6 32
VERZCO R*4 Z coordinate of the vertex. 500 10**6 32
VERTOF R*4 Vertex time of flight. 2100 10**4 32
VERTNO R*4 Beam track number . 0 1 7
VERTAR R*4 Target track number. 0 1 7
VERNTR R*4 Number of tracks generated. 0 1 3
-------------------------------------------------------------------
VERTLS R*4 First offset to track number. 0 1 7
.... ....
VERUSR R*4 Number of following user words 0 1 3
.... ....
YBOS Bank header:
-----------------
Bank Name: DHIT
Bank Number: 1
Bank Data Length:
Bank Type: BNKTR4 ! R*4
Each word in the bank can be located through the offsets shown below.
-------------------------------------------------------------------
offset word type description enc. offsets scales bits
-------------------------------------------------------------------
DHIHDS I*4 Header length (words)
DHIVRN I*4 Version number
DHINRO I*4 Number of hits 0 1 32
DHINCO I*4 Number of elements/hit
-------------------------------------------------------------------
DHIPTY I*4 Particle type 0 1 8
DHITRA I*4 Pointer to KINE bank 0 1 7
DHIADR I*4 Cell address: wire and plane 0 1 16
(packed: 2**9*plane+wire)
DHIXCO R*4 X 200 10**6 32
DHIYCO R*4 Y 200 10**6 32
DHIZCO R*4 Z 200 10**6 32
DHIPPX R*4 Px 5*10**5 10**3 32
DHIPPY R*4 Py 5*10**5 10**3 32
DHIPPZ R*4 Pz 5*10**5 10**3 32
DHITOF R*4 Time 2000 10**5 32
DHIELO R*4 Energy loss inside the cell 0 10**4 16
DHILEN R*4 Track length inside the cell 0 10 16
DHITIM R*4 Drift time (ns) 0. 1 13
DHIDIS R*4 Distance from the wire 5. 200 11
DHIFLA I*4 packed flag 0. 1 8
(10*number of times the particle crosses
chamber walls + number of crossed wires)
-------------------------------------------------------------------
YBOS Bank header:
-----------------
Bank Name: CHIT
Bank Number: 1
Bank Data Length:
Bank Type: BNKTR4 ! R*4
Each word in the bank can be located through the offsets shown below.
-------------------------------------------------------------------
offset word type description enc. offsets scales bits
-------------------------------------------------------------------
CHIHDS I*4 Header length (words)
CHIVRN I*4 Version number
CHINRO I*4 Number of hits 0 1 32
CHINCO I*4 Number of elements/hit
-------------------------------------------------------------------
CHIPTY I*4 Particle type 0 1 8
CHITRA I*4 Pointer to KINE bank 0 1 7
CHIADR I*4 Cell address : 0 1 16
column,plane,wedge,cal. number
(packed: see CELE bank)
CHIXCO R*4 X (average) 300 10 13
CHIYCO R*4 Y (average) 300 10 13
CHIZCO R*4 Z (average) 300 10 13
CHITOF R*4 Time (average) 2000 100 32
CHIELO R*4 Energy loss inside the cell 0 1000 18
CHILEN R*4 Track length inside the cell 0 100 14
-------------------------------------------------------------------
YBOS Bank header:
-----------------
Bank Name: CFHI
Bank Number: 1
Bank Data Length:
Bank Type: BNKTR4 ! R*4
Each word in the bank can be located through the offsets shown below.
-------------------------------------------------------------------
offset word type description enc. offsets scales bits
-------------------------------------------------------------------
CFHHDS I*4 Header length (words)
CFHVRN I*4 Version number
CFHNRO I*4 Number of impact points 0 1 32
+ conversion points
CFHNCO I*4 Number of elements/
impact point,conv.p.
-------------------------------------------------------------------
CFHPTY I*4 Particle type 0 1 8
CFHTRA I*4 Pointer to KINE bank 0 1 7
CFHADR I*4 Cell address : 0 1 16
(CHIT/CELE coding)
+15th bit set in case of
conversion point
CFHXCO R*4 X 300 50 15
CFHYCO R*4 Y 300 50 15
CFHZCO R*4 Z 300 50 15
CFHPPX R*4 Px 5*10**5 10**3 32
CFHPPY R*4 Py 5*10**5 10**3 32
CFHPPZ R*4 Pz 5*10**5 10**3 32
CFHTOF R*4 Time 2000 100 32
CFHLEN R*4 Total track length 0 100 32
of the impinging particle.
-------------------------------------------------------------------
YBOS Bank header:
-----------------
Bank Name: AHIT
Bank Number: 1
Bank Data Length:
Bank Type: BNKTR4 ! R*4
Each word in the bank can be located through the offsets shown below.
-------------------------------------------------------------------
offset word type description enc. offsets scales bits
-------------------------------------------------------------------
AHIHDS I*4 Header length (words)
AHIVRN I*4 Version number
AHINRO I*4 Number of hits 0 1 32
AHINCO I*4 Number of elements/hit
-------------------------------------------------------------------
AHIPTY I*4 Particle type 0 1 8
AHITRA I*4 Pointer to KINE bank 0 1 7
AHIADR I*4 Address : anticoincidences 0 1 16
numbered following z-axis
AHIXCO R*4 X 300 50 15
AHIYCO R*4 Y 300 50 15
AHIZCO R*4 Z 300 50 15
AHIPPX R*4 Px 10**5 10**4 32
AHIPPY R*4 Py 10**5 10**4 32
AHIPPZ R*4 Pz 10**5 10**4 32
AHITOF R*4 Time 0 10**4 32
AHIELO R*4 Energy loss 0 10**3 21
AHILEN R*4 Track length inside 0 50 11
the anticoinc.
-------------------------------------------------------------------
YBOS Bank header:
-----------------
Bank Name: QHIT
Bank Number: 1
Bank Data Length:
Bank Type: BNKTR4 ! R*4
Each word in the bank can be located through the offsets shown below.
-------------------------------------------------------------------
offset word type description enc. offsets scales bits
-------------------------------------------------------------------
QHIHDS I*4 Header length (words)
QHIVRN I*4 Version number
QHINRO I*4 Number of hits 0 1 32
QHINCO I*4 Number of elements/hit
-------------------------------------------------------------------
QHIPTY I*4 Particle type 0 1 8
QHITRA I*4 Pointer to KINE bank 0 1 7
QHIADR I*4 Address : quadrupole 0 1 16
numbered following z-axis
QHIXCO R*4 X impinging point 300 50 15
QHIYCO R*4 Y impinging point 300 50 15
QHIZCO R*4 Z impinging point 300 50 15
QHIPPX R*4 Px impinging point 10**5 10**4 32
QHIPPY R*4 Py impinging point 10**5 10**4 32
QHIPPZ R*4 Pz impinging point 10**5 10**4 32
QHITOF R*4 Time impinging point 0 10**4 32
QHIELO R*4 Energy loss inside the quad 0 10**3 21
QHILEN R*4 Track length inside the quad 0 50 11
-------------------------------------------------------------------
YBOS Bank header:
-----------------
Bank Name: QIHI
Bank Number: 1
Bank Data Length:
Bank Type: BNKTR4 ! R*4
Each word in the bank can be located through the offsets shown below.
-------------------------------------------------------------------
offset word type description enc. offsets scales bits
-------------------------------------------------------------------
QIHHDS I*4 Header length (words)
QIHVRN I*4 Version number
QIHNRO I*4 Number of hits 0 1 32
QIHNCO I*4 Number of elements/hit
-------------------------------------------------------------------
QIHPTY I*4 Particle type 0 1 8
QIHTRA I*4 Pointer to KINE bank 0 1 7
QIHADR I*4 Address : numbered 0 1 17
following z-axis
QIHXCO R*4 X impinging point 300 50 15
QIHYCO R*4 Y impinging point 300 50 15
QIHZCO R*4 Z impinging point 300 50 15
QIHPPX R*4 Px impinging point 5*10**5 10**3 32
QIHPPY R*4 Py impinging point 5*10**5 10**3 32
QIHPPZ R*4 Pz impinging point 5*10**5 10**3 32
QIHTOF R*4 Time impinging point 2000 10**2 32
QIHELO R*4 Energy loss inside quad instr 0 10**3 21
QIHLEN R*4 Track length inside quad instr 0 20 11
-------------------------------------------------------------------
The CELE bank stores calibrated energy and time information for each element
of the calorimeter. It has the following YBOS header characteristics:
Bank Name: "CELE"
Bank Number: 1
Bank Data Length: HDSIZE+NELE*NVAL (in 4 bytes words)
Bank Type: MIXED (integer*4 + real4)
-------------------------------------------------------------------
Offset Word type Description enc. offsets scales bits
-------------------------------------------------------------------
CELHDS I*4 Header size HDSIZE
CELVRN I*4 Bank version number
CELCAL I*4 Calibration information 0 1 32
CELNRO I*4 Number of elements (NELE) 0 1 32
CELNCO I*4 Values per element (NVAL)
-------------------------------------------------------------------
HDSIZE+
CELADR+
(I-1)*NVAL I*4 Packed address \ 0 1 16
HDSIZE+
CELEA +
(I-1)*NVAL R*4 Energy side A \ 0 50 13
HDSIZE+
CELEB +
(I-1)*NVAL R*4 Energy side B - 0 50 13
HDSIZE+
CELTA +
(I-1)*NVAL R*4 Time side A / 0 100 23
HDSIZE+
CELTB +
(I-1)*NVAL R*4 Time side B / 0 100 23
-------------------------------------------------------------------
Bank Name: "CEKA"
Bank Number: 1
Bank Data Length: HDSIZE+NELE*NVAL (in 4 bytes words)
Bank Type: BNKTI4 (integer*4 )
-------------------------------------------------------------------
Offset Word type Description enc. offsets scales bits
-------------------------------------------------------------------
CEKHDS I*4 Header size HDSIZE
CEKVRN I*4 Bank version number
CEKNRO I*4 Number of elements (NELE) 0 1 32
-------------------------------------------------------------------
CEKNTR I*4 Number of KINE tracks 0 1 3
per element (NVAL)
HDSIZE+CEKADR
+(I-1)*NVAL
I*4 Kine Bank Pointer 0 1 7
-------------------------------------------------------------------
The DTCE bank contains the time and the charge values of the Drift Chamber obtained with calibration from the raw ADC and TDC banks.
The sign of the drift time pointed to by DTCTIM is (conventionally) connected to the way in which a track crosses a wire (see ARGUS NIM paper). Time smearing of 4-5 ns in GEANFI somewhat smears this connection close to the wire. Before using this time in inversion of the st relations, an absolute value must be taken.
YBOS Bank header:
-----------------
Bank Name: DTCE
Bank Number: 1, 2 (see Kloe Note 137)
Bank Data Length:
Bank Type: (I4,2R4)
The Bank is structured in a header block followed by a data block. Each word in the bank can be located through the offset shown below.
---------------------------------------------------------------
offset word type description enc. offsets scales bits
---------------------------------------------------------------
DTCHDS I*4 header size
DTCVRN I*4 bank Version Number
DTCNRO I*4 number of rows (NROW) 0 1 32
(DC hits - no hit duplicates)
DTCNCO I*4 number of data words/row
(NCOL)
---------------------------------------------------------------
DTCADR I*4 first sense wire address 0 1 32
DTCTIM R*4 first time value 6000 1 31
DTCCHA R*4 first charge value 0 1 1
.... ....
The DTKA bank only exists for Montecarlo data. After the header, for each hit in DTCE/DHRE one (variable-length) list of the indices of all KINE tracks connected to that hit is stored: the first word of a N+1-long list (N.GE.1) is the number of linked tracks, the following N words are the indices themselves.
YBOS Bank header:
-----------------
Bank Name: DTKA
Bank Number: 1
Bank Data Length:
Bank Type: BNKTI4
The Bank is structured in a header block followed by a data block.
--------------------------------------------------------------
offset word type description enc. offsets scales bits
--------------------------------------------------------------
DTKHDS I*4 header size
DTKVRN I*4 bank Version Number
DTKNRO I*4 number of rows 0 1 32
--------------------------------------------------------------
DTKNTR I*4 Number of KINE tracks 0 1 3
linked to hit n.1
DTKADR I*4 First track index 0 1 7
... I*4 Second = = 0 1 7
... I*4 .... 0 1 7
--------------------------------------------------------------
The DTHA bank only exists for Montecarlo data. It contains, for each hit in DTCE/DHRE, the index of the original DHIT hit. There may be several DHIT hits in a same DC cell, but the TDC is triggered only once, by the cluster which arrives firston the wire: only this hit is stored in DTCE/DHRE, which have less rows than DHIT. So this pointer is needed if one wants, for a given ``physical'' hit, to retrieve all of its MC-true information. Should one want to analyze the ``obscured'' hits (for obscure reasons!) one can always look for DHIT rows which are NOT represented in DTHA.
YBOS Bank header:
-----------------
Bank Name: DTHA
Bank Number: 1
Bank Data Length:
Bank Type: BNKTI4
The Bank is structured in a header block followed by a data block.
--------------------------------------------------------------
offset word type description enc. offsets scales bits
--------------------------------------------------------------
DTHHDS I*4 header size
DTHVRN I*4 bank Version Number
DTHNRO I*4 number of rows 0 1 16
(DC hits - no hit duplicates)
--------------------------------------------------------------
DTHADR I*4 Index (1-->n.of DC hits) 0 1 16
into DHIT
.... .... 0 1 16
The QCAE bank contains the time and the charge values of the QCAL calorimeters, obtained with calibration from the raw ADC and TDC banks.
YBOS Bank header:
-----------------
Bank Name: QCAE
Bank Number: 1
Bank Data Length:
Bank Type: Mixed
The Bank is structured in a header block followed by a data block. Each word in the bank can be located through the offset shown below.
--------------------------------------------------------------- offset word type description enc. offsets scales bits --------------------------------------------------------------
QCAHDS I*4 Header size HDSIZE QCAVRN I*4 Bank version number QCACAL I*4 Calibration information 0 1 32 QCANRO I*4 Number of elements (NELE) 0 1 32 QCANCO I*4 Values per element (NVAL) ------------------------------------------------------------------- HDSIZE + QCADR + (I-1)*NVAL I*4 Packed address 0 1 16 HDSIZE + QCAE + (I-1)*NVAL R*4 Energy 0 50 13 HDSIZE + QCAT + (I-1)*NVAL R*4 Time 0 100 23 -------------------------------------------------------------------
The QCKA bank only exists for Montecarlo data. After the header, for each hit in QCAE one (variable-length) list of the indices of all KINE tracks connected to that hit is stored: the first word is the number of linked tracks, the following N words are the indices themselves.
YBOS Bank header:
-----------------
Bank Name: QCKA
Bank Number: 1
Bank Data Length:
Bank Type: BNKTI4
The Bank is structured in a header block followed by a data block.
--------------------------------------------------------------
offset word type description enc. offsets scales bits
--------------------------------------------------------------
QCKHDS I*4 header size
QCKVRN I*4 bank Version Number
QCKNRO I*4 number of rows 0 1 32
--------------------------------------------------------------
QCKNTR I*4 Number of KINE tracks 0 1 3
linked to hit n.1
QCKADR I*4 First track index 0 1 7
... I*4 Second = = 0 1 7
... I*4 .... 0 1 7
--------------------------------------------------------------
In order to maintain the compatibility with all the existent reconstruction and analysis procedures an A_C module, namely KBKMDD, has been created and tested on Montecarlo banks.
The idea is to read the packed, lower-case banks, together with the information collected in the ***I banks, and to create the usual banks that can be used by any other package in the A_C job.
To activate the procedure the users must include KBKMDD before any other module when they create their own job. A KBKMDD.dict file is available in the K_SQZ area, and it will can be addressed by any A_C program to declare the module itself.
C. Bloise
August 15 1997