The MUPAGE code was developed for the production of atmospheric muon bundles on the underwater detector CAN surface, without a full Monte Carlo simulation but using parametric formulas described in Ref. [1].
The first release was written by G. Carminati, M. Bazzotti, A. Margiotta, M. Spurio in 2007 within the ANTARES Collaboration and described in Ref. [2].
The code is maintained by the KM3NeT collaboration since v3r5.
- The code tested on gcc version 11.4.0 (Ubuntu 22.04.5 LTS), root-6.28.04, 11.5.0 (Rocky Linux9)
- It was also tested on macOS Sequoia (with CMake only)
Then you can build the code using either make or CMake.
Remaining in the mupage directory, you can proceed with the basic code compiling typing
./configure
make
and run the code with
./test.sh
To build with CMake use :
mkdir build
cd build
cmake .. -DKM3NET_MUPAGE_ENABLE_ANTARES=OFF -DKM3NET_MUPAGE_ENABLE_KM3NET=OFF -DCMAKE_BUILD_TYPE=Release
cmake --build . --target install
- In
test.shit is possible to modify the random seed, the run number and the number of events to generate. It is also possible to choose the name and in which folder output files will be written by MUPAGE code and select the detector (by default, there is the most updated). Furthermore it is possible to choose the output format among the availabe ones. To see the complete list of running options and how to use them type
./mupage.exe -h
-
dat/parameters.datis the minimum configuraiton file; it is possible to modify the minimum and the maximum value of muon multiplicity, the minimum and the maximum value of the radial distribution for multiple muons, the range of zenithal angle and the seawater density. It is also possible to generate events with a threshold energy (larger than 0.001 TeV, that is the minimum generable energy). Beside each parameter you find the description of it (see Ref. [2]) and the units to use. Default values fromsrc/Parameters.ccare used for the non set variables. -
dat/parameters_original.datwhich has explicit parametrisation values from [1]. -
dat/parameters_DAEMON.datwhich is based on the fit of the DAEMON flux model https://github.com/mceq-project/daemonflux. -
dat/parameters_CORSIKA_Sibyll2.3d.datwhich is based on the fit of the CORSIKA Sibyll 2.3d simulations https://doi.org/10.1140/epjc/s10052-024-13018-8 .
WARNING: Use the reported units!
-
NB: In file
dat/parameters.datthe seawater density is reported. For not using, set it up as 1. -
NB: In file
dat/parameters.datthe MULTmax default parameter is setted up as 1000. If a smaller detector than ANTARES full detector is used,MULTmaxcan be fixed as 100. This doesn't cause a physical information losing, but a lot of CPU time can be saved. In this way, the running process can be faster also of a factor 4. -
We provide python notebooks in
notebooksto plot the parametrisations.
MUPAGE generates two output files:
1. event output file: file containing the events generated by the code. In the native format, it is an ASCII file. The first line reports the run number and the second one the livetime and its error expressed in seconds. The following lines report the info of the generated muons in a formatted table where columns are:
- the event id
- the muon id in the event
- the muon vertex coordinates in meters
- the muon direction cosines
- the muon energy in GeV
- event time
- the muon delay time in ns respect to the bundle core arrival to the can
- muon (event) weight
Run Number: 23
livetime: 0.143 0.0
1 1 1.551e+02 2.995e+02 3.140e+02 6.468e-01 1.927e-01 -7.379e-01 5.855e+03 0.000e+00 1.108e-03
2 1 -7.941e+01 -1.501e+01 3.140e+02 5.878e-01 -1.219e-01 -7.998e-01 8.504e+03 0.000e+00 9.641e-04
3 1 -3.515e+01 2.180e+02 3.140e+02 -1.094e-01 2.275e-01 -9.676e-01 5.921e+03 0.000e+00 6.815e-04
4 1 6.688e+01 -1.108e+02 3.140e+02 -7.755e-01 -3.659e-01 -5.145e-01 1.272e+02 1.136e+01 1.288e-03
4 2 7.265e+01 -1.093e+02 3.140e+02 -7.755e-01 -3.659e-01 -5.145e-01 4.903e+03 -5.481e+00 1.288e-03
...
...
...
2. livetime output file: file containg info about the generated livetime. This is an ASCII file reporting the number
of generated events and how many of these events are arriving on the upper disk of the detector can. In the table, the user can find the
values used to compute the equivalent livetime for every range of zenithal angles. N* is the number of single events generated on the
upper disk of the CAN in that specific range of zenithal angles. Delta N* is the statistical (Poisson) error of N*. N*_MC is the
expected rate of single muon events at that given solid angle. T is the equivalent livetime (T = N*/N*_MC) and Delta T is the
statistical error (Delta T = Delta N*/N*_MC).
The average livetime is the weighted average of all livetimes in that table with the error computed as the square root of the variance. The method to compute the equivalent livetime of a run is described in Ref. [2].
An example of the livetime output file is below:
Generated events: 1000
Generated events with multiplicity 1 on the upper disk of the CAN: 555
Events with energy higher than energy of threshold: 1000
Events with energy lower than energy of threshold: 0
theta (degrees) N* Delta N* N*_MC T (sec) Delta T
****************************************************************
[0,10] 34 6 22.9 1.49 0.3
]10,12] 16 4 9.6 1.67 0.4
]12,14] 26 5 11.0 2.35 0.5
]14,16] 17 4 12.4 1.37 0.3
]16,18] 25 5 13.5 1.85 0.4
]18,20] 18 4 14.5 1.24 0.3
...
...
...
Average livetime = (1.54 pm 0.07) sec
= (1.78e-05 pm 8e-07) days
-
src/mupage.cc: C++ code; MUPAGE main source there. -
dat/parameters.dat: input file with some default parameters:- the ANTARES detector CAN parameters and its depth (for default,
parameters are taken from the
$THRONG_DIR/DETECTOR/d10_c00_s00.detfile); - the zenith angle range;
- parameters for multiplicity, radial distribution, energy spectra (see Ref. [2]);
- seawater density
- threshold energy
- the ANTARES detector CAN parameters and its depth (for default,
parameters are taken from the
-
inc/Date.hh&& src/Date.cc`: library to write processing date and time (by G.Carminati, A.Sottoriva) -
inc/Muons.hh&&src/Muons.cc: class to generate an event -
inc/OutputWriter*.hh&&src/OutputWriter*.cc: classes to write event output files in different formats -
inc/Parameters.hh&&src/Parameters.cc: class with parameters from "A parameterisation of single and multiple muons in the deep water or ice" by Y.Becherini et al., AstroPart. Phys.25 (2006) 1-13 and used in MUPAGE code yo compute parametric formulas. -
inc/Vector.hh&&src/Vector.cc: class to store 2D and 3D vectors
[1] A parameterisation of single and multiple muons in the deep water or ice https://doi.org/10.1016/j.astropartphys.2005.10.005
[2] Atmospheric MUons from PArametric formulas: a fast GEnerator for neutrino telescopes (MUPAGE) https://arxiv.org/pdf/0802.0562.pdf