4. How to optimize my simulation?

4.1. General

• Normally, the user may handle chook.f in the user’s application area to get a desired output from Cosmos.

• However, in some case, the user may want to introduce non default effects (say, an electric field dependent on the particle position), which cannot be handled by using the input “namelist” data.

• For such a purpose, several files are prepared in $LIBLOFT/Header. They are summarized in Table 4.1

Table 4.1 cmy-type program files

file	used to specify or add	called when
cmyBfield.f	non-default magnetic field	ObjFile is non blank
cmyEfield.f	complex electric field	HowEfield ==2
cmyCerenkov.f	treatment of Cerenkov light	Trace > 160
cmyTracePlus.f	to show the shower spread scale	the user puts call cmyTracePlus``in ``chookBgEvent
cthinning.f	non default thinning	ThinSampling = T
chookHybAs.f	non default analytical AS generation	Generate contains as
chookEabsorb.f	non default dead particles treatment	Eabsorb ! = 0

• Their handling scheme is summarized here. We assume environmental variables $LIBLOFT and $COSMOSTOP have been set. In what follows, when “Cosmos” is used to show a file path, it means $COSMOSTOP (so, Cosmos/cosmos means $COSMOSTOP/cosmos; Similarly, LibLoft is used as $LIBLOFT.)

• As mentioned abvoe, chook.f is used to handle the program run. It contains #include "cmain.f", which is located in Cosmos/cosmos. The cmain.f contains lines:

  #include "cmyBfield.f"
  #include "cmyBfield.f"
  #include "chookHybAS.f"
  #include "chookEabsorb.f"
  #include "cthinning.f"
  #include "cmyCerenkov.f"
  #include "cmyTracePlus.f"
  

• “cpp” (C pre-processor) tries to find af file (xxx) specified by a #include "xxx", as follows. Suppose the file which contains this include statement is in a folder A. + Then, “xxx” is first sought for in the folder A (the definition of the “current folder” for “cpp”). + If not found, the folders specified by $INCHEADER are examined. + $INCHEADER is defined in “site.config” as -I./ -I$COSMOSINC -I$LIBLOFTINC, where $COSMOSINC is defined as $COSMOSTOP/cosmos and $LIBLOFTINC as $LIBLOFT/Header [1] . + So the current application area is first examined. If not found, Cosmos/cosmos, and if not, lastly LibLoft/Header. + Of course, if the last search fails, the compilation stops with an “error message”.

[1]

Instead of -I./, -./ was wrongly used in some old site.config

• Sppose the following cases + In the user’s application area, there is no “special files” such as cmyBfield.f etc (default status). In this case, the special files will be obtained from LibLoft/Header. + One or more of the special files are copied to the user’s application area but the user neither modify them nor touch chook.f and/or namelist input so that the special files are affected by that. In this case, the ones in the application area will be used but there will be no change from the previous case. + If some of copied “special file” are modified and chook.f and namelist input are also adjusted to be consistent with the modifications, the non-default behavior of the program run will be realized. + The user should not insert #include "cmyBfield.f" etc in chook.f nor add .o files to “objs” (say objs = chook.o in chook.mk.

4.1.1. Details of each special file case

4.1.1.1. cmyBfield.f

• The default magnetic field is the Geomagnetic field for the Earth. It is the IGRF version. The year is fixed by “YearOfGeomag” in the namelist.

• To give a different magnetic field for the Earth or non-Earth environment, cmyBfield.f must be copied to the user’s application area.One example is in cosmosx/Application/Example/Sun. We employ a model constructed by Hakamada. The code is put in LibLoft/Env/Sun/Import/SunMag_PFSS_by_Hakamada/

In the program, the folllowing is mentioned.

References for PFSS model:

[1] K. Hakamada, M. Kojima, T. Ohmi, M. Tokumaru, and K.Fujiki, Sol. Phys. 227, 387 (2005).

[2] K. Hakamada, Sol. Phys. 159, 89 (1995).

Not sure the above is relevant or not.

To do a Cosmos job with the magnetic field of the Sun [2] .

[2]

In what follows, “done” means, the described action has been done already

cmyBfield.f:

Copy LibLoft/Header/cmyBfield.f to the Applications/Example/Sun/ (done). Modify the program to include call calcmagFE(...) which is an interface routine (in C-language) to the Hakamada’s routines (done).The interface routines are placed in LibLoft/Env/Sun/Import/SunMag_PFSS_by_Hakamada/Interface/

SunDef.d:

Make this data file in which &ObjParam namelist data to describe the Sun is given (done). The name, SunDef.d, may be arbitrary but the namelist name, &ObjParam should be kept.

ObjFile:

The file name, SunDef.d in this case, must be spcified by a variable, ObjFile in &Hparam (done).

SunAtmos.d, AtmosFile, AtmosModel:

To define the sun’s atmosphere, the user must create a file (in this example, SunAtmos.d) in which a 3-column table of “height(m) temperature(K) and density(kg/m3) exist (done)). The name must be given in the AtmosFile variable in &Hparam where AtmosModel = 3 (see the next item) must also be given (done).

atmosModel.sh:

The description is for building with legacy make.

The user can verify the current atmosphere model by calling a script, “atmosModel.sh”. The script is stored in Cosmos/Scrpt/. (So it’s better to put Cosmos/Scrpt in the PATH envrionmental variable). Invoking the command shows the current atmosphere model (1-standard for the Earth, 2-time and location dependent NRL atmosphere for the Earth, 3-special one like for the sun.) If needed, the user can change the model, and the library will be renewed. Note that this action only changes the library so the user must recompile own application.

Also see Section 4.5 .

4.1.1.2. cmyEfield.f

See Section 4.6 .

4.2. Hadronic interaction model

ON GOING

Hadronic interaction models are selected through IntModel in the param file. An example found in the FirstKiss sample is:

IntModel = '"phits" 2.0 "dpmjet3" ',

meaning PHITS and DPMJET3 are used below and above 2 GeV, respectively.

Table 4.2 Available versions of hadronic interaction models

Model	Name in param	Environmental var.	Env. Value	Comments
QGSJET II-03	qgsjet2	QGS	qgsjetII-03
QGSJET II-04	qgsjet2	QGS	qgsjetII-04	default of QGSJET
QGSJET III	qgsjet2	QGS	qgsjetIII
SIBYLL 2.1	sibyll	SIBYLL	sibyll2.1
SIBYLL 2.3c	sibyll	SIBYLL	sibyll2.3c
SIBYLL 2.3d	sibyll	SIBYLL	sibyll2.3d
EPOS LHC v3700	epos	EPOS	epos-lhc-v3700
EPOS LHC v3400	epos	EPOS	epos-lhc-v3400
EPOS v1.99	epos	EPOS	epos199

The list of available models and the versions of each model are summarized in Table 5.2 . For the models, QGSJET, SIBYLL, and EPOS, you can select a version. When you build the library, set the corresponding environmental variable in the 3rd column in Table 4.2 to the value in the 4th column. When you want to use the QGSJET-III model for example, build the library with the following command:

env QGS=qgsjetIII ./Script/CompileLibraryByCMake.sh

Build an executable and run with parameter like

IntModel = '"phits" 2.0 "dpmjet3" 80 "qgsjet2"'

QGSJET-III will be used for interactions above 80 GeV.

If you use legacy make, move to the directory $COSMOSTOP/LibLoft/Scrpt, and type:

intModel.sh

You can find choices of high energy hadronic interaction models, qgsjet2, epos and sibyll, and current version. If you want to switch between the versions, you can select from the list shown.

4.3. Thinning

4.4. AS, hybrid method

4.5. Magnetic field

The magnetic field is controlled by the parameter HowGeomag. By default, HowGeomag is 11 where constant magnetic field will be applied, calculated by the IGRF model at the date of YearOfGeomag at the place of the detector system at (LatitOfSite, LongitOfSite).

Table 4.3 HowGeomag parameter

HowGeomag	description
1	no magnetic field is taken into account until the first collision. The field is position dependent and calculated with the IGRF model at each position.
2	magnetic field exists everywhere. The field is position dependent and calculated with the IGRF model at each position.
11	same as 1 but constant. The field is calculated with the IGRF model at BaseL.
12	same as 2 but constant. The field is calculated with the IGRF model at BaseL.
21	same as 1 but constant. The field is defined by MagN, MagE and MagD parameters in &HPARAM.
22	same as 2 but constant. The field is defined by MagN, MagE and MagD parameters in &HPARAM.
31	same as 1
32	same as 12
others	same as one of the above

In most cases, HowGeomag=11 is recommended but when Reverse is not 0 (back-tracking is enabled), please set HowGeomag=2.

When you want to define arbitrary magnetic field, in environment such as another planet, you have to define subroutine cmyBfield( yearin, pos, MagF, icon ) and ObjFile to enable the subroutine.

4.6. Electric field

4.6.1. Introduction

Simple but unrealistic electric fields can be used without any coding by the user. It may be used to see the basic effect of electric field on charged particle motion. If the user wants to use more realistic field effect, it is better to make the cosmos library following the procedure described in Section 4.6.3.

In every case, the field strength must be given in unit of V/m. The final field vector, \(\vec{\mathcal{E}}\), must be given in the E-xyz system.

4.6.2. Simple electric field

An electric field can be specified by referring to the height(H), distance to the shower axis (R) and time information (T) of each charged particle, where H is the height in m a.s.l, R (in m) the horizontal distance if DefofR='h' (default) or perpendicular distance if DefofR='p', T the time (in ns) spent from the starting point of the primary particle.

• If T is used, H is neglected.

• So the field is determined by H and R or T and R.

• If R is not given, only H or T is used.

• If neither H nor T is used, only R is used.

• If non of H,T,R is used, the filed will be 0.

To specify H,T,R, a variable, myEf and its components are used. For example, if the user want to give an electric field at \(0<H<1000\) and \(2000<H<3000\), respectively

myEf(1)%H1=0
myEf(1)%H2=1000
myEf(2)%H1=2000
myEf(2)%H2=3000

may be given in the param file. Corresponding field vectors may be given as

myEf(1)%Ef=Ex,Ey,Ez
myEf(2)%Ef=Ex',Ey',Ez'

where Ex etc are numerical values in V/m. The vectors must be given in the detector system (vertically upward direction is the +Z direction. Internally, the values are converted into the ones in the E-xyz system.

The height list by myEf must be given from lower ones (note: the observation height list in the param file is given from higher to lower height order). For T, R, the same format is used. The max number of fields is 5.

To activate the specifications by myEf, HowEfield=1 must be given in the &HPARAM section of param file. Its default is 0 which means non-existence of the electric field.

4.6.3. Arbitrary electric field

To use more realistic fields, the user must define a subroutine whose name is cmyEfield(aTrack, Efout), where aTrack is the track information in the E-xyz coordinate system and Efout is the electric field the user should define in the E-xyz system. And finally HowEfield=2 should be specified in the &HPARAM section of param file at run.

Even if cmyEfield() is defined as above, the user can set HowEfield=0 or 1.

Let’s assume the filename cmyEfield.f where cmyEfield(aTrack, Efout) is defined.

1. First, copy $LIBLOFT/Header/cmyEfield.f to your project directory. The local file, ./cmyEfield.f will be automatically included in the build process.

2. Edit cmyEfield.f to define customized electric field, cmyEfield(aTrack, Efout).

3. Build executable as described in Section 2.4.

An example project to enable arbitrary electric field can be found in Application/Example/MyField/, which will be useful as a template. (see Section 6.3 )

4.7. Non-air material, non-earth sphere

Usually air shower simulation codes handle only air (mixture of \(\mathrm{N}_2\) , \(\mathrm{O}_2\) and other rarer gas) as a medium. Also usual simulation codes assume a flat atmosphere or a spherically symmetric atmosphere centered at the center of the earth. However, COSMOS X allows to arrange non-air material such as water and soil. Their shapes are limited in shells with a common center, but the radius is not limited to the radius of the earth. This means COSMOS X is able to simulate air showers in the other planets, or stars including their ground.

To define non-standard environment, users can use a variable ObjFile in the param file such as:

ObjFile = ”obsfile”

Here obsfile is a file name that contains actual definition of the environment. When the ObjFile variable is not specified in the param file, usual atmosphere is setup.

4.8. User defined Trace output