README.md 3.87 KB
Newer Older
Ralf Ulrich's avatar
Ralf Ulrich committed
1 2
# CORSIKA8 Framework for Particle Cascades in Astroparticle Physics**

Ralf Ulrich's avatar
Ralf Ulrich committed
3 4 5 6 7 8 9
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.
Ralf Ulrich's avatar
Ralf Ulrich committed
10 11 12 13 14 15

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
only specific model parameters can still be changed.

Ralf Ulrich's avatar
Ralf Ulrich committed
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
CORSIKA8 is released under the GPL3 license. This does not exclude
that specific CORSIKA8 versions can be released for specific purposes
under different licensing. See [license
which is part of every release and the source code.

If you use, or want to refer to, CORSIKA8 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](https://doi.org/10.1007/s41781-018-0013-0). We kindly ask (and
expect) any relevant improvement or addition to be offered or
contributed to the main CORSIKA8 repository for the benefit of the
whole community.

When you plan to contribute to CORSIKA8 check the guidelines outlined here:
guidelines](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/CONTRIBUTING.md). 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 CORSIKA8
project and you should include yourself in the

IMPORTANT: Before you contribute, you need to read and agree to the
agreement](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/COLLABORATION_AGREEMENT.md). The
agreement can be discussed, and eventually improved.

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

## Get in contact
  * Connect to https://gitlab.ikp.kit.edu; register yourself and join the "Air Shower Physics" group
  * 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
Ralf Ulrich's avatar
Ralf Ulrich committed
55 56 57 58

## Installation

59 60 61
CORSIKA8 is tested regularly at least on gcc7.3.0 and clang-6.0.0.
Additional software prerequisites: eigen3, boost, cmake, g++, git. 
On a bare Ubuntu 18.04, just add:
Ralf Ulrich's avatar
Ralf Ulrich committed
Hans Dembinski's avatar
Hans Dembinski committed
sudo apt-get install libeigen3-dev libboost-dev cmake g++ git
Ralf Ulrich's avatar
Ralf Ulrich committed
64 65

Follow these steps to download and install CORSIKA8-milestone2
Ralf Ulrich's avatar
Ralf Ulrich committed
67 68 69
git clone git@gitlab.ikp.kit.edu:AirShowerPhysics/corsika.git
cd corsika
git checkout milestone2
Ralf Ulrich's avatar
Ralf Ulrich committed
71 72 73 74 75 76 77
mkdir ../corsika-build
cd ../corsika-build
cmake ../corsika -DCMAKE_INSTALL_PREFIX=../corsika-install
make -j8
make install
make test
78 79 80 81 82 83 84 85
and if you want to see how the first simple hadron cascade develops, see `Documentation/Examples/cascade_example.cc` for a starting point. 

Run the cascade_example with: 
cd ../corsika-install

Maximilian Reininghaus's avatar
Maximilian Reininghaus committed
Visualize output (needs gnuplot installed): 
87 88 89 90
bash share/tools/plot_tracks.sh tracks.dat 
firefox tracks.dat.gif 
Hans Dembinski's avatar
Hans Dembinski committed
91 92 93 94 95 96 97 98 99 100

### Generating doxygen documentation

To generate the documentation, you need doxygen and graphviz. On Ubuntu 18.04, do:
sudo apt-get install doxygen graphviz
Switch to the corsika build directory and do
make doxygen
make install
Hans Dembinski's avatar
Hans Dembinski committed
103 104 105 106
browse with firefox:
firefox ../corsika-install/share/doc/html/index.html