IAP GITLAB

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

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
Ralf Ulrich's avatar
Ralf Ulrich committed
14
model parameters can still be changed.
Ralf Ulrich's avatar
Ralf Ulrich committed
15

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
Ralf Ulrich's avatar
Ralf Ulrich committed
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

IMPORTANT: Before you contribute, you need to read and agree to the
[collaboration
Ralf Ulrich's avatar
Ralf Ulrich committed
38
agreement](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/COLLABORATION_AGREEMENT.md). The agreement can be discussed, and eventually improved.
Ralf Ulrich's avatar
Ralf Ulrich committed
39 40

We also want to point you to the [MCnet
Ralf Ulrich's avatar
Ralf Ulrich committed
41
guidelines](https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika/blob/master/MCNET_GUIDELINES), which are very useful also for us.
Ralf Ulrich's avatar
Ralf Ulrich committed
42 43 44


## Get in contact
Ralf Ulrich's avatar
Ralf Ulrich committed
45
  * Connect to https://gitlab.ikp.kit.edu register yourself and join the "Air Shower Physics" group. Write to me (ralf.ulrich@kit.edu) only in case there are problems with that. 
Ralf Ulrich's avatar
Ralf Ulrich committed
46 47
  * Connect to corsika-devel@lists.kit.edu (self-register at
    https://www.lists.kit.edu/sympa/subscribe/corsika-devel) to get in
Ralf Ulrich's avatar
Ralf Ulrich committed
48 49 50
    touch with the project.
    
  * Register on the corsika slack channel. 
Ralf Ulrich's avatar
Ralf Ulrich committed
51 52


Ralf Ulrich's avatar
Ralf Ulrich committed
53
## Installation
Ralf Ulrich's avatar
Ralf Ulrich committed
54

Ralf Ulrich's avatar
Ralf Ulrich committed
55
CORSIKA 8 is tested regularly at least on gcc7.3.0 and clang-8.0.0. 
56

Ralf Ulrich's avatar
Ralf Ulrich committed
57 58 59 60 61 62
### Prerequisites

You will also need:

- Python 3 (supported versions are Python >= 3.6), with pip
- conan (via pip)
63 64
- cmake 
- git
Ralf Ulrich's avatar
Ralf Ulrich committed
65
- g++, gfortran, binutils, make
66

67
On a bare Ubuntu 18.04, just add:
68
``` shell
Ralf Ulrich's avatar
Ralf Ulrich committed
69
sudo apt-get install python3 python3-pip cmake g++ gfortran binutils make git 
Ralf Ulrich's avatar
Ralf Ulrich committed
70
```
Ralf Ulrich's avatar
Ralf Ulrich committed
71

72 73 74 75 76
CORSIKA 8 uses the [conan](https://conan.io/) package manager to manage our
dependencies. If you do not have Conan installed, it can be installed with:

``` shell
pip install --user conan
Ralf Ulrich's avatar
Ralf Ulrich committed
77
```
78

Ralf Ulrich's avatar
Ralf Ulrich committed
79 80
### Compiling

81
Once Conan is installed, follow these steps to download and install CORSIKA 8:
Ralf Ulrich's avatar
Ralf Ulrich committed
82

83
``` shell
84
git clone --recursive git@gitlab.ikp.kit.edu:AirShowerPhysics/corsika.git
Ralf Ulrich's avatar
Ralf Ulrich committed
85 86
mkdir corsika-build
cd corsika-build
Ralf Ulrich's avatar
Ralf Ulrich committed
87 88 89 90
cmake ../corsika -DCMAKE_INSTALL_PREFIX=../corsika-install
make -j8
make install
```
Ralf Ulrich's avatar
Ralf Ulrich committed
91 92 93 94 95 96 97 98 99 100 101 102 103


## 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
Ralf Ulrich's avatar
Ralf Ulrich committed
104
```shell
Ralf Ulrich's avatar
Ralf Ulrich committed
105 106 107 108
git clone --recursive https://gitlab.ikp.kit.edu/AirShowerPhysics/corsika.git
sudo docker run -v $PWD:/corsika -it corsika/devel:clang-8 /bin/bash
mkdir build
cd build
Ralf Ulrich's avatar
Ralf Ulrich committed
109
cmake ../corsika -DCMAKE_INSTALL_PREFIX=../corsika-install
Ralf Ulrich's avatar
Ralf Ulrich committed
110 111 112 113
make -j8
make install
```

Ralf Ulrich's avatar
Ralf Ulrich committed
114 115 116 117 118 119 120 121
## Runing Unit Tests

Note, before you run *any* executbale you must also define the
`CORSIKA_DATA` environment variable to point to the location where you
cloned corsika `modules/data`, thus typically 
```shell
export CORSIKA_DATA=$PWD/../corsika/modules/data
```
Ralf Ulrich's avatar
Ralf Ulrich committed
122

Ralf Ulrich's avatar
Ralf Ulrich committed
123
To run the Unit Tests, just type `ctest` in your build area.
Ralf Ulrich's avatar
Ralf Ulrich committed
124

125

Ralf Ulrich's avatar
Ralf Ulrich committed
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
## Running examples

To see how a relatively simple hadron cascade develops,
see `examples/cascade_example.cpp` for a starting point.

To run the cascade_example, or any other CORSIKA 8 application, you
must first compile it wrt. to the CORSIKA 8 header-only framework.  This
can be done best by copying
e.g. `corsika-install/share/corsika/examples/` to your working place
(e.g. `corsika-work`). 

Next, you need to define the environment variable `corsika_DIR` to point to, either, 
your build, or your install area. Thus, e.g. 
```shell
export corsika_DIR=<dir where you installed CORSIKA 8 to, or where you buld it">
141
```
Ralf Ulrich's avatar
Ralf Ulrich committed
142 143 144 145 146 147 148

Then compile your example/application with
```shell
cd corsika-work
cmake .
make
bin/cascade_example 
149 150
```

Maximilian Reininghaus's avatar
Maximilian Reininghaus committed
151
Visualize output (needs gnuplot installed): 
Ralf Ulrich's avatar
Ralf Ulrich committed
152 153
```shell
bash $corsika_DIR/share/corsika/tools/plot_tracks.sh tracks.dat 
154 155
firefox tracks.dat.gif 
```
Ralf Ulrich's avatar
Ralf Ulrich committed
156 157
(note, if you use the corsika_DIR to point to the build area: the script `plot_tracks.sh` is 
not copied to the build area, it is only part of the source tree at `tools/plot_tracks.sh`)
Hans Dembinski's avatar
Hans Dembinski committed
158

Ralf Ulrich's avatar
Ralf Ulrich committed
159 160 161
Or also consider the `vertical_EAS` example in the same directory,
which can be configured with command line options. 
Run `bin/vertical_EAS` to get basic help.
Ralf Ulrich's avatar
Ralf Ulrich committed
162 163


Hans Dembinski's avatar
Hans Dembinski committed
164 165
### Generating doxygen documentation

Ralf Ulrich's avatar
Ralf Ulrich committed
166 167
To generate the documentation, you need doxygen and graphviz. If you work with 
the docker corsika/devel containers this is already included. 
Ralf Ulrich's avatar
Ralf Ulrich committed
168
Otherwise, e.g. on Ubuntu 18.04, do:
Ralf Ulrich's avatar
Ralf Ulrich committed
169
```shell
Hans Dembinski's avatar
Hans Dembinski committed
170 171 172
sudo apt-get install doxygen graphviz
```
Switch to the corsika build directory and do
Ralf Ulrich's avatar
Ralf Ulrich committed
173
```shell
Hans Dembinski's avatar
Hans Dembinski committed
174
make doxygen
175
make install
Hans Dembinski's avatar
Hans Dembinski committed
176
```
Ralf Ulrich's avatar
Ralf Ulrich committed
177 178 179
open with firefox:
```shell
firefox ../corsika-install/share/corsika/doc/html/index.html
180
```
Ralf Ulrich's avatar
doxygen  
Ralf Ulrich committed
181