IAP GITLAB

README.md 4.67 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.

Ralf Ulrich's avatar
Ralf Ulrich committed
16
CORSIKA 8 is by default released under the GPLv3 license. See [license
Ralf Ulrich's avatar
Ralf Ulrich committed
17 18 19
file](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/LICENSE)
which is part of every release and the source code.

20
If you use, or want to refer to, CORSIKA 8 please cite ["Towards a Next
Ralf Ulrich's avatar
Ralf Ulrich committed
21 22 23
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
Ralf Ulrich's avatar
Ralf Ulrich committed
24
require) any relevant improvement or addition to be offered or
25
contributed to the main CORSIKA 8 repository for the benefit of the
Ralf Ulrich's avatar
Ralf Ulrich committed
26 27
whole community.

28
When you plan to contribute to CORSIKA 8 check the guidelines outlined here:
Ralf Ulrich's avatar
Ralf Ulrich committed
29 30 31 32
[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
33
been accepted and merged you become a contributor of the CORSIKA 8
Ralf Ulrich's avatar
Ralf Ulrich committed
34
project (code author). 
Ralf Ulrich's avatar
Ralf Ulrich committed
35 36 37 38 39 40 41 42 43 44 45 46

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
47
  * Connect to https://gitlab.ikp.kit.edu register yourself and join the "Air Shower Physics" group
Ralf Ulrich's avatar
Ralf Ulrich committed
48 49 50
  * 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
51 52


Ralf Ulrich's avatar
Ralf Ulrich committed
53

54 55
CORSIKA 8 is tested regularly at least on gcc7.3.0 and clang-8.0.0.
Additional software prerequisites you need to install are: eigen3, zlib, libbz2, cmake, g++, git. 
56

57
On a bare Ubuntu 18.04, just add:
Ralf Ulrich's avatar
Ralf Ulrich committed
58
```
59
sudo apt install libeigen3-dev zlib1g-dev libbz2-dev cmake g++ git
Ralf Ulrich's avatar
Ralf Ulrich committed
60
```
Ralf Ulrich's avatar
Ralf Ulrich committed
61

62
Follow these steps to download and install CORSIKA 8
Ralf Ulrich's avatar
Ralf Ulrich committed
63
```
64
git clone --recursive git@gitlab.ikp.kit.edu:AirShowerPhysics/corsika.git
Ralf Ulrich's avatar
Ralf Ulrich committed
65 66 67 68 69 70 71
cd corsika
mkdir ../corsika-build
cd ../corsika-build
cmake ../corsika -DCMAKE_INSTALL_PREFIX=../corsika-install
make -j8
make install
```
Ralf Ulrich's avatar
Ralf Ulrich committed
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98

Type `make test` to run the unit test suite.

## Installation (using docker containers)

There are docker containers prepared that bring all the environment and packages you need to run CORSIKA. See [docker hub](https://hub.docker.com/repository/docker/corsika/devel) 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
```
git clone --recursive https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika.git
cd corsika
sudo docker run -v $PWD:/corsika -it corsika/devel:clang-8 /bin/bash
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=../install
make -j8
make install
```

Type `make test` to run the unit test suite.

99
### Running examples
Ralf Ulrich's avatar
Ralf Ulrich committed
100

101
and if you want to see how the first simple hadron cascade develops, see `Documentation/Examples/cascade_example.cc` for a starting point. 
102 103 104 105 106 107 108

Run the cascade_example with: 
```
cd ../corsika-install
share/examples/cascade_example
```

Maximilian Reininghaus's avatar
Maximilian Reininghaus committed
109
Visualize output (needs gnuplot installed): 
110 111 112 113
```
bash share/tools/plot_tracks.sh tracks.dat 
firefox tracks.dat.gif 
```
Hans Dembinski's avatar
Hans Dembinski committed
114

Ralf Ulrich's avatar
Ralf Ulrich committed
115
Or also consider the `vertical_EAS` example in the same directory, which can 
Ralf Ulrich's avatar
Ralf Ulrich committed
116 117 118
be configured with command line options. 


Hans Dembinski's avatar
Hans Dembinski committed
119 120
### Generating doxygen documentation

Ralf Ulrich's avatar
Ralf Ulrich committed
121 122
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 18.04, do:
Hans Dembinski's avatar
Hans Dembinski committed
123 124 125 126 127 128
```
sudo apt-get install doxygen graphviz
```
Switch to the corsika build directory and do
```
make doxygen
129
make install
Hans Dembinski's avatar
Hans Dembinski committed
130
```
131 132 133 134
browse with firefox:
```
firefox ../corsika-install/share/doc/html/index.html
```
Ralf Ulrich's avatar
doxygen  
Ralf Ulrich committed
135