2. How to use COSMOS X for the first time?

2.1. Environment

COSMOS X is developed mainly under Linux and Mac OS X with Intel or gFortran compilers. Both conventional make and recent cmake are available for compilation, but the development team eventually unifies to cmake. List of successful combinations of OS version, distribution, compiler version are given in the official COSMOS web page,

http://cosmos.icrr.u-tokyo.ac.jp/COSMOSweb/

It is clear that the list is not complete. Any feedback (both success and failure) from the users to cosmos@icrr.u-tokyo.ac.jp are highly welcome.

2.2. Download

The source codes of COSMOS are packed in a single tar.gz file. First download the latest version from the COSMOS page introduced in Section 2.1 .

2.3. Installation

Installation procedure depends if cmake is available or not. The scripts are prepared for bash/zsh 1 .

• gunzip CosmosX_zzzzz.tar.gz to unpack the package, where zzzzz designates the version number.

• tar xvf CosmosX_zzzz.tar to unpack the tar archive.

• cd CosmosX-zzzzz, where is called CosmosX directory hereafter

  1. If you can use cmake

     • less Doc/HowToBuildByCMake.txt to know the procedure

     • source Script/SetEnvironment.sh to set environment variables. You can answer yes for 2 questions. The top directory of COSMOS X is assigned to the environment variable $COSMOSTOP.

     • ./Script/CompileLibraryByCMake.sh to make library

     • if you find lib/LinuxGfort/libshowermc.a compilation is successful (in case of using Linux gFortran.)

  2. if you can not use cmake (use legacy make)

     • cd Cosmos

     • ls Site to find a site.configXXX file fitting to your environment where XXX designates architecture and compiler

     • cp Site/site.configXXX site.config to copy a proper config file in the Cosmos/ directory

     • cd .., then repeat same in the LibLoft directory

     • move back to the CosmosX directory

     • source Script/SetEnvironment.sh to set environment variables. You can answer yes for 2 questions. The top directory of COSMOS X is assigned to the environment variable $COSMOSTOP.

     • TEMPORAL NOTE: if your meet an error message -bash: ${yn,,}: bad substitution, remove ,, in SetEnvironment.sh.

     • ./Script/CompileByLegacyMake.sh to make library

     • if you find lib/LinuxGfort/libshowermc.a compilation is successful (in case of using Linux gFortran.)

1

If you use (t)csh, please set the environment variables as follows instead of running SetEnvironment.sh.

setenv SHOWERMCTOP /somewhere/CosmosX-zzzzz
setenv LIBLOFT   $SHOWERMCTOP/LibLoft
setenv COSMOSTOP $SHOWERMCTOP/Cosmos
setenv HOST $HOSTNAME # if $HOST is not defined

2.4. Test program (First Kiss)

The related files of the first example application are found in the Application/Example/FirstKiss/ directory. Let us play with this example.

2.4.1. Compile and Run

1. If you can use cmake

   • move to the CosmosX directory

     ./Script/CompileExampleByCMake.sh ./Application/Example/FirstKiss
     cd Application/Example/FirstKiss
     

2. if you can not use cmake

   cd Application/Example/FirstKiss
   make clean -f Makefile.legacy
   make -f Makefile.legacy
   

   • if you find cosmosXXX executable file, compilation is successful, where XXX depends on your system ( XXX =LinuxGfort, for example)

   • ./cosmosLinuxGfort < param to start a simulation lasting for some minutes depending on the system

According to the primary and param files, this sample code simulates two showers of Nitrogen primary with kinetic energy of 100 GeV/n.

2.4.2. Track visualization

After a simulation, you can find trace files such as trace1 and trace2 for each primary injection. If you are in the FirstKiss/ directory and be able to launch ROOT, type

cd Vis
root ReadTraceMacro.C

to visualize the shower image as shown in Fig. 2.1 . The ROOT code explains how to visualize the trace information. You can use your preferable graphical libraries. Because the size of the trace files gets large, to inactivate the trace output you can edit param file and change Trace=0.

Format of the trace file in case of Trace=21 as found in the FirstKiss sample is:

x y z PID Ekin Q t

where (x, y, z) is the position of the particle in meter in the coordinate system with z-axis directing vertical (detector system, See Section 2), PID is the particle identification code ( Section 5.1), Ekin is the particle kinetic energy in GeV, Q is the charge in e and t is the time in nsec. Options of the Trace value are summarized in Table 3.1.

Output of trace file is defined in Cosmos/Tracking/cputTrInfo.f. When you want to define the output of the trace file as you like, set the Trace value larger than 100 and edit the subroutine chookTrace in chook.f. Detail is given in Section 4.7.

Fig. 2.1 ROOT visualization of a 100 GeV/n nitrogen shower in the FirstKiss sample.

2.4.3. Userhook output

As seen in Listing 1.3, the main code of FirstKiss, chook.f, contains a subroutine chookObs(aTrack,id) , which outputs particle information in air shower. As seen in Fig. 1.1, chookObs(aTrack,id) subroutine is called from the system subroutine cobservation() in Cosmos/Tracking/cobservation.f every time a particle reaches at the observation levels.The observation levels can be defined in the param file with a variable DepthList in \(\mathrm{kg/m}^2\) , or alternatively HeightList in \(\mathrm{m}\).

The variable aTrack given from the system subroutine has a structure type track defined in Cosmos/include/Ztrack.h. The member variables defined in the track structure are listed in Table 2.1 . To access these variables, as found in chook.f, we can use such as aTrack%where and aTrack%p%mass.

Table 2.1 Definition of the variables found in track structure

variable	variable type	description
p	struct ptcl	particle attributes defined in Zptcl.h
pos	struct position	position, structure defined in Zpos.h
t	real*8	time in length/beta (m)
vec	struct direc
wgt	real*4	weight for thin sampling
where	integer*2	current obsSite no. (0 is initial value)
asflag	integer*2	non 0, if As has been generated from this ptcl (only for electrons)
user	real*8	user use
If LABELING>0
label	integer	put a label (1,2,…) on each particle. There is a global label counter which is cleared at the start of 1 event generation. It is counted up when a particle is poped up from the stack. The label counter is given to the label of the poped up particle. This may be needed to judge if the same particle crosses a given observation place more than once.
info	integer	for each particle, when a particle is born this is initialized to 0. If the ptcl goes higher than 380km, 1 is added. This is for AMS observation.