Flyo is a Montecarlo written in C++ for the simulation of nuclear events within a complex experimental apparatus. The user describes the apparatus and the chain of the reactions in ASCII files with .app or .epc extensions. The apparatus is made up of detectors (or devices) that are described into logical segments, called blocks, containing specific keywords (or control words) followed by parameters written in free-format.
Flyo reads from the input files all the data and generates a logical architecture that reflects the experimental set-up and builds a seriee of nuclear reactions as required by the user. After a short initialization, Flyo simulates, for each event, the beam and all the particles partaining the selected reactions. Each particle is then drawn through the experimental apparatus taking into account the materials found in detectors and traversed along the path. In the case of dense material, Flyo, if enabled by the user, generates bremsstrahlung and pair production. It also memorizes, inside the internal buffers of each hit detectors, many information of all particles seen by the device, like coordinates, energy and momentum, etcc.
After the tracking, the hits seen by the various devices are elaborated to generate more specific informations in agreement with the device functions. Now the data are similar to the data “rough” generated by a real experimental set-up, but filled with more information derived by he Monte Carlo generation.
The last phase is the analysis that could be done just at the end of each event generation. So Flyo, if instructed , processes the “rough” data by reconstructing the events (geometrically and kinematic-ally) according to certain hypothesis set by the user in the file type epc.
Flyo produces output in two files, a complete listing (like a debugging) with all the information of the parameters of production and a ROOT file containing all or the events selected by a user-defined criteria.
A first input file type app describes with same details, the optical beam from the target production up to the beginning of the area of the detectors. A second file app describes the detectors used in the experiment as designed by researchers
The file epc is the file that contains all the parameters and the description of the 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 app files needed for a complete description of the experimental set-up.
In next chapters we will talk mainly of the file app or epc. There we describe the meaning and the format of the keywords that are read by Flyo for the initialization of the various procedures of simulation and analysis. Then we'll turn to specific chapters still in progress.
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
You will get all the informations shown in the figure here at side. The source is all in the folder src while the apparatus and reaction descriptions are in Epc.
Now type make to compile the program that you will find in binary in the bin/ with a name Flyo.
Your computer, running Linux (CERN Scientific Linux or Fedora 6 or even more recently OS like UBUNTU ...), must have good C++ compiler, version 3.2.3 or greater and the Root library of CERN.
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 to the line command. For example, always in your Epc folder, write:
$>
../bin/Flyo -d path/risultati/ -i kpivv/Kpivv.epc -t root -r 3333 -e
20000
This is a command that prompts you to generate 20,000 events as described in the file Kpivv.epc and creates 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 in order to avoid confusion between the sources of the program and with the results, it is appropriate to call it off! such as in home/user/results and it should be created before using it.
Remember that the paths are subject to change if you put yourself in a folder different from that mentioned earlier. You must then pass the path relative to the point where you run, or you put the absolute path!
If you repeat the run with the same number already used, the old file is not overwritten, but a new file is written with the same run number followed by a + (order num.).
Because root does not handle files larger than 1.4 Gb, attention to defining an adequate total number of events. If it is too large you risk of losing the job. Consider produce more runs with different numbers to force flyo to generate independent series of events ( random initialization dependes on correlation setting; correlation = 1).
The
file
app
are
text files that describe geometrically the detectors with the
materials they are made and list the particles that they are able to
reveal.
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 real
information is usually started by a control word or keyword and are
on a line. Multiple lines form a block which is usually closed by an
end
or
fine.
The labels or numbers after the keyword must be separated by one or
more spaces, but it is not necessary to write data in fixed format.
The
material parameters are wired directly into the program source
Flyo. 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 by the procedures part_db_dbs.cpp while with the command
pr_data_bas Flyo prints out the complete list of particles
used into the simulation.
A control word like 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!.
We use the following units:
Length in cm (Centimeter)
Energy in GeV (Gigaelect.)
Pulse in GeV/c (Gigaelect./c)
Time in ns (Nanosecond)
Detectors are described in file.app. To understand better the description you must represent the detector as a solid consisting of an outer surface, an interior region sensitive to particles, and an empty hole for the beam.
You can see an example of a file.App, and recognize the keywords described below
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.
Flyo according to this word creates an object which is then better defined in the following lines. [In the following, after the list of keywords are listed the various types of equipment already programmed into Flyo. New devices derived from the lower class, can still be added to the user's pleasure.]
name is followed by the real dev name as defined by the user and a NICK_NAME used in ROOT. If the NICK_NAME is missing, ROOT uses the name.
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 or no, 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 remains in the file for future reference.
flags is followed by a parameter that specifies a general function performed by the whole 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.
dead or rtrigh the particles leave the detector a signal that can be used for the trigger.The tracking is finished.
dump the particles leave all his energy in the detector, so they are terminated
detect This control word specifies in detail the behavior of the detector when a particle passes 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 you may add:
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 (C=cieco!)
enevd if you want to record all the energy of the particle in the device and you want to continue the tracing.
More lines with the word "detect" may appear one after the other and Flyo works respecting the order of the list. So if the particle pim (negative pion) appears in a line detect the device detects and records the corresponding hit on a counter. In the final output appears explicitly the number of times that the pim was seen by the particle detector. If then a line appears with "detect char" all other charged particles are detected, may be recorded or not (or NOREG cdump) and later reported in the final listing without pim.
materials is followed by two labels: the abbreviations of the materials corresponding to the internal structure of the device, the second label defines the material that fills the hole inside (usually empty!). (A detector is essentially thought made of an outer surface, an interior sensitive to particle and a hole (buco) in which the beam passes.)
pair it enables, if it is enabled also in general (see), 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 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 after 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. Indicates a variable field and programmed in the class corresponding to the structure being created. In the case of a quadrupole, the first number indicates the strength of the field kGauss, the second number indicates how far from the center field is measured.
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, thre numbers; 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 signal the end of the block device. end_all end all device blocks. Note: end end end_all for Flyo are equivalent.
The epc file defines the main parameters of a run and reports the descriptions of the reactions.
Let's start with a sample file, the file Kpipi060.epc or similar. This is one of the files that define the parameters of a simulation run, and describe 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, any file can easily be included with a simple command include set in the right place of a epc file to restore the continuity of information for Flyo. It is preferred to separate them to make easier the editing without the risk of confusion. For example the first two .app files are more stable, but the third, which describes in particular the reactions, should be promptly updated according to user requirements.
Remember that in launching Flyo, as mentioned above you type
../bin/Flyo -d path/risultati/ -i kpivv/Kpivv.epc -r 3333 -e 20000
if you are in in the folder Epc. If you launch Flyo from another location it is necessary to adjust the paths in relation to the new location.
And now we come to the explanation of the contents of this last .epc 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.
dgbin Flyo writes out each line read from the input file. It is a command usefully for debugging of the input files especially when there are reading errors that stop the program.
run is the default number of runs. [In the command line the option -r at the of departure of 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 manner in which Fyo initializes the random routine: with 0 the initialization is always the same, 1 initialization depends on the run number, finally if it is >1 the random initialization depends on the run and event. In this case, two simulations, with the same number of runs, have the same initialization for the event with the same number. This can be useful if you want to check the effect of small variations of the device; but certainly is more time comnsuming!
errors Flyo introduces errors in the generated data.
scatter in the track events Flyo takes into account the multiple scattering.
loss Flyo calculate 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 also requested in the block detector.
bremsstrahlung, it activates the production of radiation bremsstrhalung
illumina activates writing of a ROOT block of data (luce) with detailed information on the generation of particles.
radx n1 n2 This activates the block radx which contains the hits of all detectors from device number n1 to n2.
trigger that writes the trigger low level informations in the ROOT block. Of course, the written information depends on how the trigger is simulated. For the moment, very roughly!
tracks forces the tracks recontruction and writes the information about the tracks on ROOT output.
User, k2pic, k4gam, k6gam, k3pic, kppgg, k3l, ka2pi, pi2g, E2G, E6G, KL2, kpc2g, kpcpi0, kpc2p0, kpivv, these are the keywords that trigger the data analysis and enable the writing of corresponding block in the ROOT output. More procedures can be activated simultaneously. Many others analisys may be programmed by the users. The procedures correspond to classes all derived from the base class analysis. To get a complete overview see directly the source or documentation generated by Doxygen.
wrtn, it instructs to write the output file with only the events that have passed at least one case analysis.
wrtnall this requires flyo to write all the events have survived the trigger zero level, regardless of whether they have successfully passed the final analysis of reconstruction.
labzero defines the absolute zero of the reference frame of the apparatus. If the three values are zerol, the coordinates of the various detectors are centered respect to lab system , otherwise the coordinates of the detectors are redefined by shifting appropriately.
fiducial is followed by two values that identify the zeta interval in which you fix the beam decay. Note the zone of confidence may be a particular part of the apparatus, however, in some cases where you want to study the decays of K even before or after a particular area, you can use a larger window of acceptance. Note, the generation of K beam is limited to those that potentially live up to the trusted zone choice, unless, during the flight 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 after the zeta here defined.
The reactions are described in a block in which they appear: information on the target, the production of the beam, the maximum deviation of the beam and the specs on the desired reaction. 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.
beam this forces the reaction to be of a beam. Used for the study of the beam.
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 while respecting the production cross sections given in the production procedure (see).
urto. 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. Flyo generates multiple reactions in proportion to the written 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 as a cylinder with axis along z.
pinch, it provides the average momentu ( 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. The real generation of the beam depends on the differential cross section as described in the production procedure (see).
upinc with the same parameters, but in this case the beam is generated with Gaussian shape around the values written: impulse and width. Flyo evoids to trace the particles along the beam optics. If it is sufficient to approximate a beam in the simulation, you go faster!
coll is a virtual collimator that has a cylindrical shape and it is tought to be on the the beam axis far from the target to define the maximum beam divergence. The numbers give the x, y, z (z is the one that counts! Unless it is willing to put the hole in the virtual collimatove a bit eccentric.), 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 in => pim pi0. The reazione itself is described by Km followed by an equal and two or more particles. Here for example
Km = 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.
pi0 = gam gam, next line that informs Flyo that the neutral pion decays into two gamma.
fine closes the block under the reaction itself began with the word reazione.
end closes the block started with decay
done closes the block.
pr_reazioni it prints out the listing of the reactions requireds.
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 elementary particles are in a data_base with all the information needed to create a list of particles (objects) used by the program in the simulation of various reactions.
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 part_db.
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 decay matrix. Each particle at the end of its travel, always ended by natural death or by 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.
| Kl = 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 dinamically 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 easy 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 case 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 code. The technique is to set up for any particular decay a virtual particle, which is inserted 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 control words, pairproduction and / or bremsstrahlung are enabled.
Gmp
next......