The ARTI Framework

A framework designed to simulate the signals produced by the secondary particles emerging from the interaction of the flux of primary cosmic ray with the atmosphere. These signals are simulated for any particle detector located at any place (latitude, longitude and altitude), including the real-time atmospheric, geomagnetic and detector conditions.

Request Feature · Report Bug · Contact us

ARTI is a complete framework designed to simulate the signals produced by the secondary particles emerging from the interaction of singles, multiple and even the complete flux of primary cosmic rays with the atmosphere. These signals are simulated for any particle detector located at any place (latitude, longitude and altitude), including the real-time atmospheric, geomagnetic and detector conditions.

Formulated through a sequence of scripts coded in C++, Fortran, and Perl, it provides an easy-to-use integration of three different simulation environments: Magneto Cosmics, CORSIKA and Geant4. These tools evaluate the geomagnetic field effects on the primary flux, the atmospheric showers of cosmic rays and the detectors' response to the secondary flux of particles produced in the atmosphere.

With ARTI it is also possible to calculate the flux of the expected signals produced by the sudden occurrence of a gamma-ray bursts or the flux of energetic photons originating in steady gamma sources. It also compares these fluxes with the expected background to detect these phenomena in a single water Cherenkov detector (WCD).

Even more, by using ARTI, it is possible to calculate in a very precise way the expected flux of high energetic muons and other secondaries on the ground and to inject it over a geological structure for muography applications.

When using ARTI, please cite the reference reported below:

Christian Sarmiento-Cano, Mauricio Suárez-Durán, Rolando Calderón-Ardila, Adriana Vásquez-Ramírez, Andrei Jaimes-Motta, Luis A. Núñez, Sergio Dasso, Iván Sidelnik and Hernán Asorey (for the LAGO Collaboration), "The ARTI Framework: Cosmic Rays Atmospheric Background Simulations", European Journal of Physics C, 82, 1019 (2022), arXiv:2010.14591[astro-ph.IM], doi:10.1140/epjc/s10052-022-10883-z. (bibtex)

(back to top)

To get a local copy up and running follow these simple example steps.

ARTI runs in any Linux based system, including iOS. For Windows user, we strongly recommend to install some of your preferred linux distribution using virtualbox. Additionally, we are developing a docker-based ARTI implementation.

In Fedora, Scientific Linux and CentOS, use sudo yum install <package>. In Ubuntu/Debian, use sudo apt install <package>. In both cases, you can also use the graphic package manager included in your preferred distro.

ARTI requires the installation of the following packages:

• bash
• perl 5.0
• perl LWD::simple module
• perl JSON module
• gcc
• make
• screen
• rsync
• git

As a one-liner for Ubuntu/Debian:

sudo apt install build-essential perl screen rsync git

(git is optional).

Additionally, ARTI depends on the previous installation of the following frameworks:

• CORSIKA v7.7402.
• ROOT v6.20.08.
• Magneto Cosmics v2.0.
• Geant v4.10.03.p03
• Geant v4.10.03 Data Libraries

Plese notice this list corresponds to the set of external dependencies of ARTI v1r9. Backward compatibility within previous minor versions and patches of the external dependencies is assured, i.e., ARTI will run with any older versions of CORSIKA v7.xxxx, ROOT v6.xx.xx and GEANT4.10.xx.xx.pxx.

CORSIKA should be compiled with the following options:

Compiler: 64bits 
High Energy Hadronic Model: QGSJETII-04
Low Energy hadronic interaction model: GHEISHA 2002d
Detector Geometry: non-flat (Volume) detector

and, for production, the following additional program options:

Landau-Pomeranchunk-Migdal (LPM) effect
Curved atmosphere version
external atmosphere functions
EFIELD

Additionally, ARTI is compatible with some other CORSIKA functionalities, such as PLOTSH, PLOTSH2. and CHERENKOV, but it is not recommended to compile CORSIKA using these options as they will strongly decrease the simulation performance and are not needed for production. A pre-compiled version of CORSIKA intended for simulation production is available upon request.

There are no other special requirements for ROOT, MAGNETOCOSMICS and GEANT4. Standard installations of these packages will smoothly work with ARTI.

1. If you are using git, just clone this repository:

   cd /path/to/ARTI/installation
   git clone https://github.com/lagoproject/arti.git

   Otherwise, you can also directly download ARTI without using git (in this case, you should reinstall ARTI for every upgrade):

   cd /path/to/ARTI/installation
   wget -c https://github.com/lagoproject/arti/archive/refs/heads/master.zip
   unzip master.zip
   rm master.zip

2. ARTI compiling is very simple:

   cd arti
   make

   1. During the first installation of ARTI (or if you need to install ARTI in a different directory), make will define the $ARTI environment variable, that points to the ARTI current directory installation. Then, ARTI installer will add the definition of this variable to the user's local .bashrc and to the local $PATH environment variable:

      #
      ## Changes added by the ARTI suite on <installation date>
      #
      export ARTI="/path/to/ARTI/installation/arti"
      export PATH="${ARTI}/sims/:${ARTI}/analysis:$PATH"

      You can edit your .bashrc to add, e.g., the directory where the CORSIKA executables files were located, for example:

      export CRK="/path/to/CORSIKA/run"
      export PATH="${CRK}/:$PATH"
      

If you follow the above described steps and everything works well, you should find some new executable files at the ${ARTI}/analysis directory.

A Docker container having all the ARTI requirements and dependencies installed and configured with the corresponding options for production is currently under development and will be available in June 2022.

If you want to receive information about the ARTI new releases, or have any doubts or require extra information about the compiling options for all these packages, please don't hesitate to contact us.

(back to top)

ARTI is continously used, revised and updated within the LAGO Collaboration.

Unless you are a developer, we recommend to use only the latest ARTI release contained in the master branch of this repository. Stable versions are tagged and can be found in the corresponding section of this repository.

Clone and install ARTI from dev or dev-* branches is strongly discouraged, as these branches are used for testing, bug correction and for the development of new features.

If you are using git, you can update ARTI just by doing:

cd /path/to/ARTI/installation/arti
git pull
make

Otherwise, you could just reinstall ARTI by following the installation guide.

(back to top)

The ARTI approach for calculation the expected flux of signals due to the integrated flux of cosmic rays is based on three stages:

1. Definition of the site characteristics, primary spectrum calculations and Extensive Air Showers (EAS) developments;
2. Analysis of the secondary particles at ground and geomagnetic corrections;
3. Detector simulation.

Depending on the type of calculation the user should need, there are different pathways that need to be followed.

The flux simulation background starts with the do_sims.sh script, as follows:

do_sims.sh -w path_to/corsika/run/ -p fluxBGA -s bga -v 77402 -t 3600 -u orcid -y -x

With this options, ARTI will integrate the expected flux of primaries during 3600 second (-t 3600) for the city of Bucaramanga, Colombia (-s bga) at an altitude of 965 m a.s.l., using a volumetric WCD (-y). EAS calculations will be done using the CORSIKA executables version 7.7402 (-v 77402) located at -w path_to/corsika/run. The user ORCID (-u orcid) will be stored in the corresponding metadata and will be preserved for future citation of the data. While it is recommended to use your ORCID, any alphanumeric string is accepted. For the rest of possible options, do_sims.sh will use the ARTI defaults (- x). Otherwise, they would be answered in an interactive ARTI session.

The list of predefined sites in ARTI is compiled and regularly updated in the LAGO Data Management Plan. ARTI includes a JSON parser to get the characteristics needed for the simulation of the flux at several predefined sites.

Defaults, included the site characteristics, can be overridden by the user by selecting the corresponding options. Please run

do_sims.sh -?

to view a brief description of the available options. The resulting files will be stored at the local directory /path_to/corsika/run/fluxBGA, automatically created from the path given with the -w option and the project name (-p fluxBGA).

The scripts and codes related with these calculations can be found in the sims directory. All of them have their own integrated help, accessible through the -? modifier.

Once the catalogues with the raw data of the flux are produced, they can be read and analysed with the ARTI analyses tools to extract the secondary particle flux information: the secondary particle ID, the particle momentum, the particle position relative to the primary core, and additional information related with its primary progenitor. Depending on the environment, the analysis stage can be performed automatically during the runtime or manually by calling to the do_showers.sh script:

$ do_showers.sh -o /path_to/corsika/run/fluxBGA -k 965 -t 3600 -g bga.geo 3 -l

With this options, ARTI will perform the standard analysis of the files located at /path_to/corsika/run/fluxBGA (-o option), corresponding to the flux of secondaries impinging 1 m2 at ground during 3600s (-t option) for a site at an altitude of 965 m a.s.l. (-k option), using the column 3 of the geomagnetic conditions file bga.geo (-g option). The analysis will be parallelized (-l) using the default number of processors equals to half the available ones, and the results will be stored in the current directory (default: $PWD, see option -w).

As in the previous case, all the codes and executables have their internal help (-?) and are available in the analysis directory.

A complete and detailed simulation of a generic and modifiable WCD Geant4 simulation is included in the wcd directory.

The main characteristics of the detector can be easily configured by editing the corresponding files in the src, such as: the water container material, thickness and geometry; the reflectivity and diffusivity of the detector's inner coating; the water absorption curves in the optical and UV wavelength range; the geometry and wavelength sensitivity of the photomultiplier tube (PMT); and the emulated response of the onboard electronic system.

Once the corresponding variables are updated in the code, it must be re-compiled by doing:

cmake -DGeant4_DIR=/path/to/geant4/lib/Geant4-version/
make -j2

and a new wcd executable file will be compiled at the wcd directory. Before to run, the file containing the secondaries at ground resulting of the previous analisys should be defined in the input.in file.

Again, depending on the environment, it could run automatically during runtime or has to be called by the user once the previous stages are completed, by doing:

wcd -m input.in > run.log

Additional information can be found in the wcd module README.md and in the ARTI Documentation.

The documentation is currently under preparation and will be released in July 2022. A brief description of the action of each code and the available options and modifiers can be seen by calling them with the -? modifier.

For more examples, please refer to the ARTI Documentation.

(back to top)

ARTI has several options and internal configurations to automatically run at different types of computing facilities: from personal notebooks or desktops up to high performance computing clusters.

More recently, oneDataSim, a cloud-based implementation of ARTI, has been developed under the LAGO Thematic Service at the European Open Science Cloud - Expanding Capacities by building Capabilities project.

By using oneDataSim, currently available through the EOSC Marketplace, it is possible to run the ARTI simulations at federated clouds, such as the European Open Scientific Cloud (EOSC) and other public clouds, such as the Google cloud, Amazon web services and Microsoft Azure.

(back to top)

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

ARTI is distributed under the BSD-3 License. See the LICENCE for more information.

(back to top)

The ARTI framework is developed by the LAGO simulation group. If you need to contact us, please complete our contact form.

ARTI principal contact: Dr. Hernán Asorey (@asoreyh)

Project Link: https://github.com/lagoproject/arti

(back to top)