Introduzione

Flyo is a Montecarlo written in C + + for the simulation of the events inside an experimental apparatus described by the user in ascii files with .app or .epc extensions. The description of the device, divided into logical segments, called block, is made up with keywords, also called control words, that are followed by parameters written in free-format.

Flyo reads all input data and creates a logical pattern that reflects the experimental setup and describes the series of nuclear reactions desired by the user. After a short initialization, the simulation procedure for each event generates the beam and all the particles required in the reactions. Each particle is drawn through the experimental apparatus taking into account the materials found in detectors traversed along the path. In the case of dense material, Flyo, if enabled by the user, generates bremsstrhalung and pair production.

After the tracking, the data generated and filtered by different simulators, are similar to the rough data generated by a real experimental setup, but with more information of Monte Carlo. So Flyo, if instructed, processes the data generated by reconstructing the events (geometrically and kinematically) according to certain assumptions set by the user in the file type epc.

Flyo produces output in two files, a complete listing with all the information of the parameters of production and a Root file containing all or some of these events accepted by a user-defined criteria.

Typically a first file type app contains basic information on the material used in construction equipment. Flyo takes account of these data, tracing the particles, to generate the multiple scattering and estimate the energy loss by ionization, to produce pairs or emit gamma rays via bremsstrhalung.

A second file type app describes, in detail if necessary, the optical beam from the target production to the useful area of the detectors. A third file app describes the detectors used in the experiment designed by researchers

The file epc is the file that contains all the parameters and the description of nuclear reactions expected in a simulation run. With the same experimental setup, you can use different file epc with descriptions of chains of different reactions. The file epc shall include, at appropriate points, the file app needed for a complete description dell'appparato experimental.

In later chapters we will talk mainly of the file app or epc. It describes the meaning and format of the keywords that are read by Flyo for the initiation of the various procedures of simulation and analysis. Then we'll turn to specific chapters still in progress.

How and where do you get Flyo

Open a web browser and go to http://pierazzini.unipi.it/giuseppe/FlyoHtml/flyoindex.html and then download.

Here is the place where you can find the latest versions of Flyo in tgz. For example, Flyo62_11.07.24h1825.tgz is the version of Flyo generated in July 24 2011 at 06.25 pm.

With one click, you are prompted to download the file to your computer. The file will be in a directory where you can decompress it with the command gunzip Flyo62_11.07.24h1825.tgz to get Flyo62_11.07.24h1825.tar. Then proceed to extract the software with the command tar-xvf Flyo62_11.07.24h1825.tar

Now type make to compile the sources to a binary program that you will find in the bin/ as Flyo.

Your computer, running Linux (CERN Scientific Linux or Ubuntu 10.04 or even more recent version), must have good C++ compiler, version 3.2.3 or greater and the Root library of CERN.

How to operate Flyo

When you turn on your computer, navigate to the folder Epc (this is not mandatory, but that's how I work) and here you write .. /bin/Flyo -h to get a mini help, which explains the information to be added in line to command. For example, always in your Epc folder, write:

../bin/Flyo -d path/risultati/ -i kpivv/Kpivv.epc -t root -r 3333 -e 20000

Command that prompts you to generate 20,000 events as described in the file Kpivv.epc and create two files, the file listing and the Root with the 3333 run, in the output folder path/results. The output folder can be anywhere, but for clarity, and not confuse the source of the program with the results, it is better to place it somewhere else. Such as in home/user/results folder that should be created before using it with a mkdir home/user/results command.

Remember that the paths have to be adjusted if you put yourself in a different folder. You must then pass the path relative to the point where you run, or you write the absolute path!

If you repeat the run with the same number the results fortunately are not overwritten!, but are written in other files with the same number as before followed by a + (plus).order_number.

Because Root does not handle files too much larger than 1 Gb, you must be careful to define the max number of events to generate. If they are too many then the run jump. Consider doing more short runs by changing the run number with correlation = 1 (The random initialization is dependent on run number).

Description of equipment

The file app are text files that describe geometrically the detectors with the materials they are made and the lists of detectable particles.
Before going into the contents of the file is good to remember that the lines that begin with some asterisk or slash are considered comment lines and thus ignored by Flyo reading. The information is usually started by a control word or keyword. Multiple lines form a block which is usually closed by an end or fine. The labels or numbers after the word control follow a logical pattern: they must be separated by one or more spaces, but it is not necessary to write data in fixed fields.

The data base

The parameters of the materials are memorized directly into the Flyo source. Refer to the source matter.cpp With the keyword pr_material Flyo prints a list of materials in the listing output. The parameters that describe the particles are generated as can be seen in the procedures part_db.cpp and the like. The command pr_data_bas does print the list of particles used by Flyo.

• Unseen nu indicates that the device does not see the neutrino. Other particles may be added if necessary. This control word can also be inserted in the file epc, however, should be used after the database was created!.

The file xyznl.app

Here I report, as an example, the file Beamk60.app which refers to the description of the optical beam K of 60 GeV / c, p Take for example what is written in the file *.app:

• device is the keyword that begins a block for the description of a detector and is always followed by a second label indicating the geometry or the class of the detector (all lengths are in centimeters). Flyo according to this word generates an object better defined in the following lines. [New device derived from the lower class, can still be added to the user's pleasure.]
• name is followed by the dev_name as defined by the user and a NICK_NAME used by Root. If the NICK_NAME is missing, Root uses the name.
• flags is followed by a parameter that specifies the function of the detector. Flyo uses it in the tracing of the particles. The possible flags are:
  • none is ignored
  • trigg a flag that is used if you activate a trigger procedure
  • veto if it is triggered the event is discarded.
  • magnet indicates it is a magnet.
  • trigh the particles leave the detector a signal that can be used for the trigger.The particle tracing is finished.
  • dead particles are terminated without a trace
  • dump the particles leave all his energy in the detector, so they are terminated

• writeout indicates that the contents of the detector (the list of particles recorded or revealed), event by event, must be written on the output data file compatible with Root. If writeout begins with an asterisk , you will not find information on the output file, but the detector is regularly used in the simulation
• exclude removes the device from the simulation, but the information remains still in the file, for a reminder.
• detect This control word specifies in detail the behavior of the device with the particles that pass through it. detect is followed by one or two pieces of information, namely the name of the particle and the function that indicates how the detector should operate on the particle. The label char, neutral or all instead of the name, indicate that all charged particles, or those simply neutral or all should be revealed. The default function is the recording of the particle in the detector, but it may indicate:
• dump if you want to record and end the tracing of the particle in the detector
• cdump if you want to end the tracing without recording
• enevd if you want to record all the energy of the particle in the device and you want to continue the tracing.
• More lines detect can appear one after the other and Flyo runs respecting the succession. So if the particle pim (negative pion) appears in a line detect the device detects and records the hit on a counter. Finally, in the final output appears explicitly the number of times that the pim was seen in the particle detector. If a line appears after detect char all other charged particles are detected, may be recorded or not (or NOREG cdump) and later included in the final listing without pim.
• materials is followed by two labels, the abbreviations of the materials corresponding to the internal structure of the first device, the second material that fills the hole inside (usually empty!). Maybe something about the structure of a detector: this is imagined consisting of layers, an outer surface, an interior sensitive to particle and a hole or buco where, for example, runs the beam.
• pair it enables the photons that pass through the detector to produce electron pairs. The number following the keyword indicates how many times we accept the cycle
• photon-> pairs-> bremsstrhalung -> couples. The pair_production is enabled only if it is turned on in general (see the keyword global). The pair production depends on the length of material traversed by the radiation.
• brems enable charged particles to produce the radiation from Bremsstrahlung, provided it is also enabled in general. The number, which follows the control word indicates how many times you can repeat the chain of production of photons from bremsstrhalung. The bremssthralung also depends on the length of material traversed by the radiation.
• field is used in cases of structure with the magnetic field. The three numbers following the keyword are the values of the magnetic field in x, y and z in kGauss.
• vfield it is used especially in the case of the quadrupoles. It indicates the intensity of a variable field. In the case of a quadrupole, the first number is the strength of the field in kGauss and the second number sets the distance in cm from the center.
• magkik is the average kik (bending power of the magnet). This' value used in the reconstruction of events, not used in simulation!
• center it is followed by three numbers, the coordinates of the center of the device in centimeters.
• cface it is always followed by three numbers that indicate the center of the upstream outer surface.
• sizeout are half the size of the detector in x, y, z, but you can also find
• totout which are the total external dimensions of the detector in x, y, z.
• sizein half the size of the inner hole of the detector in x, y, z (ie the hole), but you can also find totin is the total size of the internal detector.
• centrino are the coordinates of the hole inside the device. (Not always correspond to the center of the detector).
• rout is the size of the device, if cylindrical: radius, radius (or 0.0), half size typically in z. But you can find:
• dtot full dimensions are: diameter, diameter (or 0.0), length at z.
• rin is the size of the hole, if cylindrical: radius (or 0.0), radius, half-size in z. Or
• dtin The size is complete: diameter, diameter (or 0.0), length in zeta.
• end signals the end of the block device. end_all end all device blocks. Note end for Flyo is equivalent to end_all.

An apparatus consists of many sub devices: detectors, dump magnets, chambers, .... In the files Beamk60.app are several examples such as magnet, rectangle, ytax, quadrupole. Similar devices are all described by the same geometry, of course, followed by different values of the parameters. However Flyo in the creation of the class corresponding to one device, interprets the parameters in a correct way to take into account its real geometric structure and its functions.
The dependence of a class from the others is shown in the diagrams with detailed descriptions of the sources as reported in the doxygen documentation. Each class represents a device with all its characteristics, geometry and materials, but also with its own rules or procedures that it will apply to the particles when they pass through.

The file Apparato.app

This is the file of the experimental apparatus. Please look to one file, as example, to discover some key words not yet explained. The description of detectors does not change much compared to what we have already learned.

Note that splitting the file is only instrumental, because the three files mentioned so far may be combined into one large file. It is preferred to separate them just to make it easier to edit without the risk of confusion. For example the first two files are more stable, but the third, which describes in particular the detector apparatus, should be promptly updated according to user requirements.

The epc file.
Run parameters and description of the reactions.

Let's start with a sample file, the file Kpipi060.epc for example. This is one of the files that defines the parameters of a simulation run and describes the reactions to generate. The extension epc is different from that used for other files, but that is only for convenience and to avoid confusion with other files of type app. As usual, nothing prevents you to join the file app with this file and use it directly in Flyo. In fact, the other file system can easily be included with a simple command include file in the epc to restore the continuity of information for Flyo. Remember that in launching Flyo from the Epc directory, as mentioned above you type

../bin/Flyo -d path/risultati/ -i kpivv/Kpivv.epc -r 3333 -e 20000

Once you are in the folder Epc, you will see all the other folders containing the descriptions of the apparatus and the file epc with the reactions to be performed. If you launch Flyo from another location please adjust the paths in relation to the new location.
And now we come to the explanation of the contents of this last file. It actually can be divided into two parts: one defines the parameters of running, while a second part describing the nuclear reactions that will be generated in the simulation.
Words of the overall control of the run:

• dgbinput instructs Flyo to write out each line read from the input file. It is a command used for debugging, especially when there are reading errors that stop the program.
• run is a default number of runs. The command line -r at the time of departure Flyo, override this definition.
• maxevnt maximum number of events of default. -E in the command line, defines the true number of events to generate.
• debgf indicates the first number of the first event that we want to write extensively in the listing of output for debugging.
• debgl is the last debug event.
• correla defines the way in which Fyo initializes the random routine: with 0 the initialization is always the same, with 1 the initialization depends on the number we give to the run. In this case, two simulations, with the same number of runs have the same simulation for each event. This can be useful if you want to check the effect of small variations of the device.
• errors in the simulation data Flyo introduces errors in the parameters measured.
• scatter in the track events Flyo takes into account the multiple scattering.
• loss, Flyo calculates the energy lost, updating the energy of the particle and records the information in the detector. The loss is only active if scater was activated.
• pairprod activates the automatic production of pairs by photons. Warning! actual activity occurs in the detector, provided the paiproduction has been requested in the block detector.
• bremsstrahlung, it activates the production of radiation bremsstrhalung

Analysis control

• illumina this activates the writing to a Root block luce of detailed information on the generation of particles.
• radx n1 n2 This activates the block radx which contains the hits of all detectors from n1 to n2.
• info it activates the information block of the beam (little used).
• trigger that activates the trigger information block at level 0. Of course, the written information depends on how the low level trigger is simulated. For the moment, very roughly!
• tracks that writes the information about the tracks reconstructed.
• beam this forces the reaction to be of a beam. Used for the study of the beam.
• k2pic, k4gam, k6gam, k3pic, kpivv, k3l,....user....etcc these are the keywords that trigger the data analysis and enable the writing of corresponding block Root on the output file. More procedures can be activated simultaneously. Check the procedures before using them. Some are incorrect or outdated.
  The procedures are all derived from the base class analysis. To get a complete overview see directly the source or the documentation generated by Doxygen.
• wrtn, it instructs to write in the output file only the events that have passed at least one case analysis.
• wrtnall this is to write all the events generated regardless of whether or not they have been analyzed
• include to include a file
• labzero defines the absolute zero of the reference frame of the apparatus. If the three values ​​are 0, the coordinates of the various detectors coincide with the values ​​of the laboratory, otherwise the coordinates of the detectors are redefined by shifting appropriately.
• fiducial is followed by two values ​​that identify zeta interval in which you want the decays of K. Note the zone of confidence may be a particular part of the apparatus, however, in some cases when you want to study the decays of K even before or after a particular area, you must use a larger window of acceptance. Note, the generation of K beam is limited to those that potentially live up to the choiced zone, unless during the flight the beam partcles are not diverted or removed by shock and absorption against other parts of the apparatus.
• zone means a value, here in Zeta, which corresponds approximately with the end of the apparatus. The particle tracing ends just past the zeta referred to as the ultimate limit.

The blocks of reactions

The reactions are described in a block in which they appear: information on the target, the production of the beam, the maximum divergence of the beam and the specs on the desired reactions. You can write multiple blocks, with different reactions and if you wish, with different beam and target. In general, the target and the beam parameters are the same unless you want to generate events simultaneously from two or more different targets.
The control word:

• decay This word begins a block of the reaction, and is followed by the name of a particle in the reaction will play the role of the beam. For example, Km, Kp, pip, pim, elec, elep ... written as they appear in data_base particles. The program will generate the particle beam of each reaction requested respecting the production cross sections wired into the program (Doble/Lau data).
• If you want to simulate a collision between the beam and target, the block begins with the word urto, but for the moment this aspect of the program has not yet been fully developed.
• rate is the production rate of the reaction. This number can usually match the value found in the books of the particle, but can be changed at will. We know that if Flyo must generate multiple reactions, these will be generated in proportion to the rates. So if there is only one reaction, the rate has no effect on production.
• target is followed by x, y, z center of the target, its radius and its length in zeta. The target is thought of as a cylinder with axis along z.
• pinch, it provides the average momentum ( px, py,pz) of the beam particles (all in GeV); the momentum semi-interval for the production of the beam; the production angle in rad, and finally the energy of protons hitting on the target.
• upinc with the same parameters, but in this case the beam is generated with Gaussian shape with the values written: impulse and width. In this last case Flyo jumps all the beam optics. If it is sufficient to approximate a beam in the simulation, you go faster!
• coll is a virtual collimator with a cylindrical shape parallel to the beam axis, used to define the maximum beam divergence. The numbers give the x, y, z (z is the one that counts! The cylinder radius defines the angle of collimation. The thickness is virtual (it's there for story).
• reazione is followed by a title, generally the formula of the reaction. For example, Km => pim pi0. The reazione itself is described by Km followed by an equal and two or more particles. Here from pim pi0, but may vary from case to case. Flyo reads the line as the decay of meson km in positive pion and neutral pion. Then follows, pi0 = gam gam to inform Flyo that the neutral pion decays into two gamma.
• fine closes the block under the reaction started with the word reazione.
• end closes the block started with decay word.
• done closes all the blocks.
• end_all to close the file.

In the folder Epc, see source software, there are numerous examples of simple and complex reactions. In some cases the decays into three, four and five bodies appear.

The lists of particles.

The reactions are organized by Flyo with the information of particles linked by C++ pointers.
The particles are made of objects with all the information derived from Data_Base, but are also arranged in the sequence in which they are created (see id here below). Each particle is identified by a:

name, written into the epc, (the same name that appears also in Data_Base); by a number
idm, i.e. an index of matter that corresponds to its position in Data_Base and by an index
id that places the particle within the reaction and, of course,
by all the physical parameters as mass, lifetime, charge ecc. See in detail the class particles.

Flyo generates events according to their probability of production, which depends on the rate and on the cross section of production from the beam in the target. So Flyo begins tracing each particle, starting just from the first, the beam, which tracks up to the moment of its natural decay if not terminated prior by a colliding with some part of the apparatus.
The decay is a standard procedure which takes into account the possible phase space and matrix. Each particle at the end of its travel, always for natural death or for absorption by a detector, is terminated by a code, which is called by Flyo fate and is also stored on the Root file output.

A decay to several bodies, such as the KL -> pi0 pi0 pi0, it is automatically split into two or more sub-decays.

K = pi0 res	first decay
res = pi0 pi0	second decay
pi0 = gam gam	first pi0 decay into two photons
pi0 = gam gam	second pi0 decay into two photons
pi0 = gam gam	third pi0 decay into two photons

where the particle res is generated with a mass compatible with the phase space; res is a virtual particle which also appears in Data_Base (among others), but it has the sole purpose of forcing Flyo to use the phase space. This process of fragmenting a decay in simple steps is useful because it allows us to use recursive kinematic procedure for the decay in three or more bodies.

Incidentally I should also mention that the above model allows us to easily enumerate the particles produced in the decay: with id = index of the mother, the first daughter is 2*id, the second 2*id+1; with this technique is easy to trace back the history of a particle.
Today Flyo numbers the particles within a reaction as mentioned above, but more for historical reasons than practical. Really C++ today provides methods (pointers) more flexible to take a complete assessment of a reaction chain.

To return to our problem of decay, we also recall the cases where you need to deal with a matrix elementy. The Monte Carlo Flyo generates events according to the matrix of decay. Of course, the procedure for the decay under consideration must be planned and scheduled in the source code. The technique is to insert for any particular decay a virtual particle automatically or manually into the appropriate point of the decay chain to force Flyo, when called, to follow specific probability distributions.

The number of particles of a reaction can also be changed dinamically during the generation of an event; that is usually done to take account, for example, of the pair production or of the photon emission by bremsstrhalung, if the pairproduction and/or bremsstrahlung are enabled.

Gmp

---