IAP GITLAB

README.md 4.21 KB
Newer Older
Ralf Ulrich's avatar
doxygen  
Ralf Ulrich committed
1
# CORSIKA 8 Framework for Particle Cascades in Astroparticle Physics 
Ralf Ulrich's avatar
Ralf Ulrich committed
2

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.

16 17
CORSIKA 8 is released under the GPLv3 license. This does not exclude
that specific CORSIKA 8 versions can be released for specific purposes
Ralf Ulrich's avatar
Ralf Ulrich committed
18 19 20 21
under different licensing. See [license
file](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/LICENSE)
which is part of every release and the source code.

22
If you use, or want to refer to, CORSIKA 8 please cite ["Towards a Next
Ralf Ulrich's avatar
Ralf Ulrich committed
23 24 25 26
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
27
contributed to the main CORSIKA 8 repository for the benefit of the
Ralf Ulrich's avatar
Ralf Ulrich committed
28 29
whole community.

30
When you plan to contribute to CORSIKA 8 check the guidelines outlined here:
Ralf Ulrich's avatar
Ralf Ulrich committed
31 32 33 34
[coding
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
35
been accepted and merged you become a contributor of the CORSIKA 8
Ralf Ulrich's avatar
Ralf Ulrich committed
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
project and you should include yourself in the
[AUTHORS](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/AUTHORS)
file.

IMPORTANT: Before you contribute, you need to read and agree to the
[collaboration
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
guidelines](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/MCNET_GUIDELINES),
which are very useful also for us.


## Get in contact
Ralf Ulrich's avatar
Ralf Ulrich committed
51
  * Connect to https://gitlab.ikp.kit.edu register yourself and join the "Air Shower Physics" group
Ralf Ulrich's avatar
Ralf Ulrich committed
52 53 54
  * 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
CORSIKA 8 is tested regularly at least on gcc7.3.0 and clang-6.0.0.
60
Additional software prerequisites: eigen3, boost, cmake, g++, git. 
Ralf Ulrich's avatar
Ralf Ulrich committed
61 62
However, eigen3 is shipped in ThirdParty directory, so any installation 
on the system is optional. 
63 64 65 66
In case one wants to use Pythia 8 for particle decays or to simulate showers
in a proton environment, Pythia has to be installed on your system and 
switched ON in CMakeLists.txt. We test with Pythia version 8.235.

67
On a bare Ubuntu 18.04, just add:
Ralf Ulrich's avatar
Ralf Ulrich committed
68
```
Ralf Ulrich's avatar
Ralf Ulrich committed
69
sudo apt install cmake g++ git
Ralf Ulrich's avatar
Ralf Ulrich committed
70
```
Ralf Ulrich's avatar
Ralf Ulrich committed
71
add ```libeigen3-dev``` if you want to use system version of eigen3.
Ralf Ulrich's avatar
Ralf Ulrich committed
72

73
Follow these steps to download and install CORSIKA 8 milestone2
Ralf Ulrich's avatar
Ralf Ulrich committed
74
```
75
git clone https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika.git
Ralf Ulrich's avatar
Ralf Ulrich committed
76 77 78 79 80 81 82 83
cd corsika
mkdir ../corsika-build
cd ../corsika-build
cmake ../corsika -DCMAKE_INSTALL_PREFIX=../corsika-install
make -j8
make install
make test
```
84 85 86 87 88 89 90 91
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
share/examples/cascade_example
```

Maximilian Reininghaus's avatar
Maximilian Reininghaus committed
92
Visualize output (needs gnuplot installed): 
93 94 95 96
```
bash share/tools/plot_tracks.sh tracks.dat 
firefox tracks.dat.gif 
```
Hans Dembinski's avatar
Hans Dembinski committed
97 98 99 100 101 102 103 104 105 106

### 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
107
make install
Hans Dembinski's avatar
Hans Dembinski committed
108
```
109 110 111 112
browse with firefox:
```
firefox ../corsika-install/share/doc/html/index.html
```
Ralf Ulrich's avatar
doxygen  
Ralf Ulrich committed
113