Skip to content
KM3NeTPublic

About

a MUon GEnerator from PArametric formulas

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

MUPAGE : a MUon GEnerator from PArametric formulas.

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.

Getting started

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

Build with make

Remaining in the mupage directory, you can proceed with the basic code compiling typing

./configure
make 

and run the code with

./test.sh

Build with CMake

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

How to modify input parameters

  • In test.sh it 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.dat is 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 from src/Parameters.cc are used for the non set variables.

  • dat/parameters_original.dat which has explicit parametrisation values from [1].

  • dat/parameters_DAEMON.dat which is based on the fit of the DAEMON flux model https://github.com/mceq-project/daemonflux.

  • dat/parameters_CORSIKA_Sibyll2.3d.dat which 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.dat the seawater density is reported. For not using, set it up as 1.

  • NB: In file dat/parameters.dat the MULTmax default parameter is setted up as 1000. If a smaller detector than ANTARES full detector is used, MULTmax can 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 notebooks to plot the parametrisations.

Output files

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

Brief description of the files

  • 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.det file);
    • the zenith angle range;
    • parameters for multiplicity, radial distribution, energy spectra (see Ref. [2]);
    • seawater density
    • threshold energy
  • 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

References:

[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

About

a MUon GEnerator from PArametric formulas

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages