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

  • ./Scrpt/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 the DepthList. So the HeightList must be accompanied by an appropriately edited DepthList like “-1 -1 -1 -1 “ when the user wants to define height values.

ASDepthList and ASHeightList

Same definition as DepthList and HeightList 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 with cont=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 the ASDepthList (or ASHeightList) 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 subroutine chookTrace 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.

subroutine  chookBgRun()

This subroutine is called when the program starts.

subroutine  chookBgEvent()

This subroutine is called every time a new injection happens. To record the information of individual primary particle, edit this routine.

subroutine  chookObs(aTrack, id)

This subroutine is called every time individual particle passes the observation levels defined by DepthList or HeightList.

subroutine  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.

subroutine  chookEnRun()

This subroutine is called when all shower trackings are completed.

subroutine  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 and MovedTrack defined as track structure found in Tab.1.

subroutine  chookEInt(never)

This subroutine is called when an electron (or positron) interaction occurs.

Parameters:

never [integer,out] :: if never is set non zero, this routine will never be called.

subroutine  chookGInt(never)

This subroutine is called when a gamma-ray interaction occurs.

subroutine  chookNEPInt(never)

This subroutine is called when a non-electromagnetic interaction occurs.