The gSeaGen code is a GENIE based application developed within the KM3NeT Collaboration to efficiently generate high statistics of the neutrino interaction events detectable in the neutrino telescopes. The gSeaGen code is able to generate events induced by all neutrino flavours, considering topological differences between track-type and shower-like events. The neutrino interaction is simulated taking into account the density and the composition of the media surrounding the detector.

Authors

Carla Distefano, INFN-LNS, Via S.Sofia 62, 95123, Catania, Italy (e-mail: diste.nosp@m.fano.nosp@m._c@ln.nosp@m.s.in.nosp@m.fn.it)

Alfonso Andres Garcia Soto, Nikhef, Science Park 904, Amsterdam 1098 XH, Netherlands (e-mail: alfon.nosp@m.sog@.nosp@m.nikhe.nosp@m.f.nl)

Piotr Kalaczynski, CAMK PAN, Bartycka 18, 00-716 Warsaw, Poland (e-mail: pkala.nosp@m.czyn.nosp@m.ski@k.nosp@m.m3ne.nosp@m.t.de)

Copyright

Getting Started

To use gSeaGen, one can:

Install it from the source
Run directly from a container

Installing from source

gSeaGen can be compiled on a Unix operating system and requires some basic tools, such as the gcc compiler suite, make and PERL. A minimal installation of gSeaGen requires only GENIE.

A number of environmental variables must be defined to compile gSeaGen:

GSEAGEN: pointing at the top level gSeaGen directory

GENIE: pointing at the top level GENIE directory

ROOTSYS: pointing at the top level ROOT directory

gSeaGen has been written using the GENIE Auk production release series and tested with GENIE version 2.12.10. It is also possible to link gSeaGen with the new Bear release series (GENIE v3.0.0 and later). In this case the GENIE environmental variables for the compilation are:

GENIE: pointing at the top level GENIE Generator directory

GENIE_REWEIGHT: pointing at the top level GENIE Reweight directory

Once the environmental variables are set, a minimal installation of gSeaGen is obtained by typing:

$ cd $GSEAGEN
$ ./configure
$ make

WARNING: Parallel make (e.g.make -j 4) will NOT work!

The configuration script allows to enable/disable features and specify paths to external libraries as the MUSIC and PROPOSAL propagators. The command:

$ ./configure --help

lists the configuration options. The configuration script also creates the shell scripts setenv.sh and setenv.csh, helping the user to prepare the environment to run the code.

Usage

To set the environment configuration required to run gSeaGen, the setenv script must be executed:

$ source $GSEAGEN/setenv.csh # (in tcsh or csh shells)

$ source $GSEAGEN/setenv.sh # (in bash shell)

The environmental variables required by GENIE and the ROOT version used during the compilation step are also set. Finally, the user can run the code with the following syntax:

$ gSeaNuEvGen [OPTIONS]

Running the code with the option -h:

$ gSeaNuEvGen -h

displays the list of the available options:

**Syntax**
 gSeaNuEvGen
           [-a generation_spectral_index]
           [-all]
           [-b n_of_bins]
           [-bedrock bedrock_height]
           [-c can_definition]
           [-C]
           [--coord UNIT:longitude,latitude]
           [--cross-sections XSecName]
           [-d depth]
           [-e min_energy,max_energy]
           [--event-generator-list list_name]
            -f simulation:flux[neutrino_code],...
       [-format output_format] 
           [-l light_absorption_lenght,[n_light_absorption_lenght]]
            -n n_of_events
           [-o output_event_file_prefix]
           [-origin X0,Y0,Z0]
           [-p]
           [-point source_info]
           [-prop prop_code]
           [-r run_number]
           [-R coordinate_rotation_matrix]
           [-rt RT_option]
           [--seed random_number_seed]
       [-utm]
           [-t min_costheta,max_costheta]
       [-time time_format:StartTime,StopTime]
           [--tune generator_tune]
           [-save saved_particles]
           [-chances chances_per_shower]
           [--rot-showers UNIT:yaw,pitch,roll]
           [-wgt weighting scheme]
           [--cr-flux CR flux model used to weight CORSIKA events]
 
 **Code Options**
 
 [] Denotes an optional argument.
 
 For more detailed description of different options, see the wiki (https://git.km3net.de/simulation/gseagen/-/wikis/home).
 
 ...
 
 ...
 
**Environmental Parameters**
 
 GSeaGen environmental parameters:
 
 GSEAGEN:     pointing to the top directory of the code [mandatory].
 
 MUSICPATH:   pointing to the directory with music input files [default: MUSICPATH = /pbs/throng/km3net/src/gSeaGen/music/2004].
 
 GMURNGFL:    pointing to file with max muon ranges [default: GMURNGFL = $GSEAGEN/dat/muon_rmax_music.dat].
 
 MEDIACOMP:   overriding the default composition for target media: SeaWater, Rock, Mantle, Crust.
                  Eg. MEDIACOMP = $GSEAGEN/dat/MediaComposition.xml
 
 PROPOSALCONF: pointing to the PROPOSAL configuration file. Default inputs are used if the env. parameter does not exist.
                  Eg. PROPOSALCONF = proposaldir/resources/config.json
 
 SYSTLIST:    pointing to the file defining the systematic parameters. The calculation is activated if the env. parameter exists.
                  Eg. SYSTLIST = $GSEAGEN/dat/SystParams.xml
 
 Based on GENIE, gSeaGen accepts all standard GENIE environmental parameters. For examples:
 
 GALGCONF:    overriding the default configuration folder [default: GALGCONF = $GENIE/config]
                  Eg. GALGCONF = $GENIE/config
              to use the default GENIE configuration folder.
 
 GXMLPATH:    to get user XML input files using GXMLPATH + default locations.

Running gSeaGen requires a pre-computed GENIE cross-section file. Official GENIE cross sections or instructions for building your own are available at http://www.genie-mc.org. By default, gSeaGen will look for the gxspl-FNALsmall.xml file in the running directory or in the one pointed by the GXMLPATH environmental variable (GENIE default).

Examples:

gSeaNuEvGen -n 1E3 -f [14]

The code will generate 1000 muon neutrinos sampling from a diffuse flux according to a power-law energy spectrum with a spectral index of -1.4. The code will also compute a weight for each event to normalize the simulation to the flux 1e-9*E-2 1/(GeV m2 s sr). Default values will be used for all other options.

gSeaGen supports BARTOL, FLUKA and HONDA atmospheric muon fluxes. Some of them are in the $GSEAGEN/dat directory and described in the $GSEAGEN/FLUX file.

gSeaNuEvGen -n 1E3 -f "HONDA:$GSEAGEN/dat/grn-ally-20-12-solmin.d[14,-14]"

In this case both muon neutrinos and anti-neutrinos will be generated and the events weights will be computed according to the HONDA fluxes in the file grn-ally-20-12-solmin.d.

It is possible to generate neutrinos from point or extended astrophysical sources. To activate this mode and to input the source information, the -point option can be used.

gSeaNuEvGen -n 1E3 -f [14] -point "FILE:$GSEAGEN/dat/AstroSource.xml"

In this case, the neutrinos are generated from the source defined in the file $GSEAGEN/dat/AstroSource.xml that can be used as a reference. When the point/extended mode is activated, gSeaGen uses the detector geographical coordinates. To set the detector coordinates option –coord must be used.

CORSIKA output files (DATxxxxxx) may be used as input for gSeaGen:

gSeaNuEvGen -f "BIN:$DIR/DAT001000"

Will process the CORSIKA output file DAT001000 located in $DIR.

There is a number of CORSIKA-specific options available in gSeaGen, e.g.

gSeaNuEvGen -f "BIN:$DIR/DAT001000" --corsika-max-nrecords 500

will read only first 500 records from the CORSIKA file.

Running

gSeaNuEvGen -f "BIN:$DIR/DAT001000" --corsika-less-verbose 1

will reduce the number of information printed while processing the file. This is particularly useful when working with low-energy simulation, containing huge numbers of events which can easily flood the output.

To only convert the CORSIKA file, without muon propagation, one can run:

gSeaNuEvGen -f "BIN:$DIR/DAT001000" --corsika-only-convert 1

For the other options, please refer to the output of gSeaNuEvGen -h and to processing of CORSIKA files with gSeaGen. Notably, there are options allowing to control what is saved in the output (-save and -write) and to increase the statistics (--muon-range-tolerance and -chances). The latter should be used with caution, as the retried events introduce a need for reweighting of the entire simulation if they are to be included in an analysis. This can be done using tools\gWeightCorsika, which is not an exact solution, however it works well within the statistical fluctuations.

Running from a container

An easier way to use gSeaGen is through the docker and singularity containers, provided in the image registry.

WARNING: although easier to use, the containers currently DO NOT support tau propagation due to legal constraints associated with the TAUSIC code (and similarly, muon propagation with MUSIC is not included). In the future it is foreseen to replace TAUSIC completely with PROPOSAL for this purpose.

Fetching an image

To fetch a docker image of v7.4.3 release, one can run:

docker pull git.km3net.de:4567/opensource/gseagen:v7.4.3-singularity

and similarly for a singularity container:

singularity pull docker://git.km3net.de:4567/opensource/gseagen:v7.4.3-singularity

To get a different tag, e.g. latest, simply replace v7.4.3-singularity by latest.

Running the container

To execute the code one can use exactly the same options as for installation from source, with the difference in calling the gSeaNuEvGen itself:

singularity exec gseagen_v7.3.0.sif gSeaNuEvGen

In this example the v7.3.0 release is ran from a singularity container. The syntax of docker is analogous here. For more advanced used of exec in both, please consult docker documentation and singularity documentation.

Citing gSeaGen

References:

S. Aiello et al. (the KM3NeT Collaboration), Computer Physics Communications 256, 107477 (2020)

Proceedings:

gSeaGen is a GENIE-based application. For information about GENIE citing rules visit https://hep.ph.liv.ac.uk/~costasa/genie/citing.html