CORSIKA 8 Framework for Particle Cascades in Astroparticle Physics

The purpose of CORSIKA is to simulate any particle cascades in astroparticle physics or astrophysical context. A lot of emphasis is put on modularity, flexibility, completeness, validation and correctness. To boost computational efficiency different techniques are provided, like thinning or cascade equations. The aim is that CORSIKA remains the most comprehensive framework for simulating particle cascades with stochastic and continuous processes.

The software makes extensive use of static design patterns and compiler optimization. Thus, the most fundamental configuration decision of the user must be performed at compile time. At run time model parameters can still be changed.

CORSIKA 8 is by default released under the GPLv3 license. See license file which is part of every release and the source code.

If you use, or want to refer to, CORSIKA 8 please cite "Towards a Next Generation of CORSIKA: A Framework for the Simulation of Particle Cascades in Astroparticle Physics", Comput.Softw.Big Sci. 3 (2019) 2. We kindly ask (and require) any relevant improvement or addition to be offered or contributed to the main CORSIKA 8 repository for the benefit of the whole community.

When you plan to contribute to CORSIKA 8 check the guidelines outlined here: coding guidelines. Code that fails the review by the CORSIKA author group must be improved before it can be merged in the official code base. After your code has been accepted and merged, you become a contributor of the CORSIKA 8 project (code author).

IMPORTANT: Before you contribute, you need to read and agree to the collaboration agreement. The agreement can be discussed, and eventually improved.

We also want to point you to the MCnet guidelines, which are very useful also for us.

Get in contact

• Join our chat threads using Mattermost via this invite link. Click the GitLab button, then Sign in with Helmholtz ID. You will be able to make an account by either finding your institution, or using your e.g. ORCID, GitHub, or Google account.

• Connect to https://gitlab.iap.kit.edu, register yourself and join the "Air Shower Physics" group. Write to us on Mattermost (in the User Questions channel), or directly contact one of the steering comittee members in case there are problems with that.

• Connect to corsika-devel@lists.kit.edu (self-register at https://www.lists.kit.edu/sympa/subscribe/corsika-devel) to get in touch with the project.

Installation

CORSIKA 8 is tested regularly at least on gcc11.0.0 and clang-14.0.0.

Prerequisites

You will also need:

• Python 3 (supported versions are Python >= 3.6), with pip
• cmake > 3.4
• git
• g++, gfortran, binutils, make
• optional: FLUKA (see below)

On a bare Ubuntu machine, just add:

sudo apt-get install python3 python3-pip cmake g++ gfortran git doxygen graphviz

On a bare CentOS 7 install python3, pip3 (pip from python3) and cmake3. Any of the devtools 7, 8, 9 should work (at least). Also initialize devtools, before building CORSIKA 8:

source /opt/rh/devtoolset-9/enable

Creating a virtual environment and Conan

It is recommended that you install CORSIKA 8 and its dependencies within a python3 virtual environment. To do so, you can run the following.

# Create the environment using your native python3 binary
python3 -m venv /path/to/new/virtual/environment/corsika-8
# Load the environment (should be run each time you open a new terminal)
source /path/to/new/virtual/environment/corsika-8/bin/activate

You will need to load the environment each time that you open a new terminal.

CORSIKA 8 uses the conan package manager to manage our dependencies. Currently, version 2.50.0 or higher is required.
Note: if you are NOT using a virtual environment, you may want to use the pip install --user flag.

pip install conan

Compiling

Once Conan is installed, follow these steps to download and install CORSIKA 8:

cd ./top/directory/for/corsika/installation
git clone --recursive git@gitlab.iap.kit.edu:AirShowerPhysics/corsika.git
# Or for https: git clone --recursive https://gitlab.iap.kit.edu/AirShowerPhysics/corsika.git
mkdir corsika-build
cd corsika-build
../corsika/conan-install.sh --source-directory ../corsika --release-with-debug
# conan-install.sh takes required options from command line to install dependencies for 'Debug', 'Release' and 'RelWithDebInfo' builds.
../corsika/corsika-cmake.sh -c "-DCMAKE_BUILD_TYPE="RelWithDebInfo" -DCMAKE_INSTALL_PREFIX=../corsika-install"
make -j4  #The number should match the number of available cores on your machine
make install

FLUKA support

For legal reasons we do not distribute/bundle FLUKA together with CORSIKA 8. If you want to use FLUKA as low-energy hadronic interaction model, you have to download it separately from (http://www.fluka.org/), which requires registering there as FLUKA user. The following should be done before compiling CORSIKA 8:

1. Note your system's version of gcc (gcc --version) and glibc (ldd --version)
2. Download the FLUKA binary, ensuring that it matches the versions you found above
3. Download the FLUKA data file (will be named something similar to fluka20xy.z-data.tar.gz).
4. Un-tar the files that you downloaded using tar -xf <filename>
5. Set environmental variables export FLUFOR=gfortran and export FLUPRO=<path to where you unzipped the files>. Note that the FLUPRO directory should contain libflukahp.a. Both of these variables will have to be set every time you open a new terminal.
6. Go to the FLUPRO directory and run make. This will compile an exe, flukahp, in your current directory.
7. Follow the normal steps to compile CORSIKA 8 (see above). However, during the cmake step, append the additional flag -DWITH_FLUKA=ON

When you install CORSIKA 8, you should see a message during the cmake step indicating the FLUKA was correctly found.

libflukahp.a found in directory <some location here> via FLUPRO environment variable
FLUKA support is enabled.

Installation (using docker containers)

There are docker containers prepared that bring all the environment and packages you need to run CORSIKA. See docker hub for a complete overview.

Prerequisites

You only need docker, e.g. on Ubunut: sudo apt-get install docker and of course root access.

Compiling

Follow these steps to download and install CORSIKA 8, master development version

cd ./top/directory/for/corsika/installation
git clone --recursive git@gitlab.iap.kit.edu:AirShowerPhysics/corsika.git
sudo docker run -v $PWD:/corsika -it corsika/devel:clang-8 /bin/bash
mkdir build
cd build
../corsika/conan-install.sh --source-directory ../corsika --release-with-debug
# conan-install.sh takes required options from command line to install dependencies for 'Debug', 'Release' and 'RelWithDebInfo' builds. 
../corsika/corsika-cmake.sh -c "-DCMAKE_BUILD_TYPE="RelWithDebInfo" -DCMAKE_INSTALL_PREFIX=../corsika-install"
make -j4  #The number should match the number of available cores on your machine
make install

Runing Unit Tests

To run the unit tests, do the following.

cd ./corsika-build
ctest -j4  #The number should match the number of available cores on your machine

Running applications and examples

Standard applications

Applications for standard use-cases are located in the applications directory. These are example scripts that can be used directly or slightly modified for your use case. See [applications/README.md] for more. The applications are compiled automatically after running make and will appear your corsika-build/bin directory. After running make install the binaries will also be copied into your corsika-install/bin directory as well.

For example, from inside your corsika-install/bin directory, run

c8_air_shower --pdg 2212 -E 1e5 -f my_shower

This will run a vertical 100 TeV proton shower and will create and put the output into ./my_shower.

Building the examples

Unlike the applications, the examples must be compiled as a second step. From your top corsika directory, (the one that includes corsika-build and corsika-install) run

export CONAN_DEPENDENCIES=$PWD/corsika-install/lib/cmake/dependencies
cmake -DCMAKE_TOOLCHAIN_FILE=${CONAN_DEPENDENCIES}/conan_toolchain.cmake -DCMAKE_PREFIX_PATH=${CONAN_DEPENDENCIES} -DCMAKE_POLICY_DEFAULT_CMP0091=NEW -DCMAKE_BUILD_TYPE=RelWithDebInfo -Dcorsika_DIR=./corsika-build  -S ./corsika/examples -B ./corsika-build-examples
cd corsika-build-examples
make -j4 #The number should match the number of available cores on your machine

You can run the examples by using the binaries in corsika-build-examples/bin/. For example:

corsika-build-examples/bin/known_particles

This will print out all of the particles that are known by CORSIKA.

Generating doxygen documentation

To generate the documentation, you need doxygen and graphviz. If you work with the docker corsika/devel containers this is already included. Otherwise, e.g. on Ubuntu machines, do:

sudo apt-get install doxygen graphviz

Switch to the corsika-build directory and do

make docs
make install

open with firefox:

firefox ../corsika-install/share/corsika/doc/html/index.html