3. How to edit the user control files?
3.1. primary file
As found in Listing 1.1, the primary file is composed of multiple text lines of two categories.
The first category such as:
'iso 14 7' 'GeV' 'KE/n' 'd' 0/
contains particle type, unit of energy, definition of energy, spectrum type and power of the flux normalization. Following list describes detail of each item, but more practical examples are found in the CosmosX/LibLoft/Data/Primary/ directory, especially the sample.d file contains the explanations and lists of available symbols.
particle type : The sample above indicates an isotope of mass number 14 and atomic number 7, i.e., Nitrogen. This is a general definition of nucleus. For other elementary and composite particles such as electrons and protons specific names, e, e-, electron and p, proton are defined, respectively. A list of definitions is found in the sample.d file.
unit of energy : Unit of energy is defined either in eV, MeV, GeV, TeV, PeV and EeV.
definition of energy : Definition of energy is available in total energy per particle (E/P or E), kinetic energy per particle (KE/P or KE), energy per nucleon (E/n), kinetic energy per nucleon (KE/n), momentum per particle (p/P or p) and momentum per nucleon (p/n). Energy and momentum are considered in the same unit with the speed of light c = 1.
spectrum type : Definition of the following flux values in differential (d) or integral (i).
flux power : Definition of the following flux values in \(\mathrm{flux}\times E^X\) Power \(X\) is indicated.
option (min and max) : As options, you can add two more values to specify the minimum and maximum energies to simulate.
Then the following lines as the second category such as:
100 1.
0. 0.
contain the energy and flux. The line with two zeros means the end of the flux data. Single non-zero line as shown here is used to make a mono-energetic incident.
To learn how primary file works, try a sample PrimaryHowTo. Here only cmake compile procedure is explained. For make compilation, please refer Section 2.4.
move to the CosmosX directory
./Script/CompileExampleByCMake.sh ./Application/Example/PrimaryHowTo
cd Application/Example/PrimaryHowTo
./cosmosLinuxGfort < param > out
If you can use ROOT,
root primary_analysis.cpp
This sample shows mixed composition primary generation without any shower simulation. After output primary information, particle track is killed in chookBgEvent
subroutine in chook.f. Any primary file you define can be tested based on this sample.
3.2. param file
Users will edit this file frequently. As seen in Listing 1.2, various parameters can be specified.
The param file is separated in two blocks. The first block enclosed by &PARAM
and &END
contains general parameters while the second block with &HPARAM
contains special parameters which users do not need to edit in the usual use. Explanation of all parameters are given in Section 3. Here some important parameters are introduced.
DepthList : List of the observation depths in \(\mathrm{kg/m}^2\) in increasing order. Userhook subroutine
chookObs
is called when a particle passes this depth. Zero means the end of the list. Negative depth values are replaced with the values in the HeightList.HeightList : List of the observation heights in \(\mathrm{m}\) in decreasing order. Userhook subroutine
chookObs
is called when a particle passes this height. End of the list is specified by zero in theDepthList
. So theHeightList
must be accompanied by an appropriately editedDepthList
like “-1 -1 -1 -1 “ when the user wants to define height values.ASDepthList and ASHeightList : Same definition as
DepthList
andHeightList
but used when Generate specifies ‘as’.DestEventNo : Number of injection to be simulated. If two numbers are given like
DestEventNo = 10000 1000
, the program run will stop at the completion of the second numver of events (1000). You may continue the job withcont=t
function (see below) for another set of (1000) events, and repeat such a process until all the first number (10,000) of events are finished.CosZenith : Ragne of the cosine zenith angle of the primaries. Set
CosZenith = (0.5, 1.0)
if you want to inject at the zenith angle between 60 degrees and vertical. Note that this zenith angle is the direction of primary particles measured at the deepest observation level. At other depths, the value is not strictly the same.Azimuth : Range of the azimuthal angle of the primaries in degrees.
PrimaryFile : Name of the file where the primaries are defined.
Generate: When
Generate = 'as'
, electro-magnetic showers are replaced with an analytical calculation of the B-approximation. Number of particles at the depths (or heights) specified in theASDepthList
(orASHeightList
) are stored. As the result is given only in 1-dimensionally, this option is useful for a fast calculation of longitudinal development or hadronic components. If you want to simulate full em showers (3D Monte Carlo) in parallel to the B-approximation,Generate = 'em/as'
can do it. Without specification of this parameter, full em showers are always active.Trace : Output of particle track information is controlled as seen in the FirstKiss example in Section 2.4. Because the size of the trace output is large, when you simulate many showers, do not forget to set
Trace = 0
. To define custom output, set the Trace value more than or equal to 100 and less than 160. Then edit the userhook subroutinechookTrace
in chook.f. See also Section 3.3.InitRN : Initial random number seeds of the first event. If you put a negative number for the second value, like
InitRN = 12345 -77777333
, Cosmos will use a timer value and the host name to make the initial seed.
3.3. userhoook subroutines
Various userhook subroutines are prepared in chook.f. Each subroutine is called when predefined conditions are satisfied in the main routines of COSMOS X. Users can edit the contents of the userhook subroutines to access the particle information, to control the output format and so on. Explanation of each userhook subroutine is given below.
chookBgRun : This subroutine is called when the program starts.
chookBgEvent : This subroutine is called every time a new injection happens. To record the information of individual primary particle, edit this routine.
chookObs(aTrack, id) : This subroutine is called every time individual particle passes the observation levels defined by
DepthList
orHeightList
.chookEnEvent : This subroutine is called when all particle tracking of each shower is completed. To output the statistics of each shower, for example, edit this routine.
chookEnRun : This subroutine is called when all shower trackings are completed.
chookTrace : This subroutine is called every time a particle moves when \(100 \leq Trace < 160\). Track information before and after movement can be accessed through the variables
TrackBefMove
andMovedTrack
defined as track structure found in Tab.1.chookEInt(never) : This subroutine is called when an electron (or positron) interaction occurs.
chookGInt(never) : This subroutine is called when a gamma-ray interaction occurs.
chookNEPInt(never) : This subroutine is called when a non-electromagnetic interaction occurs.