IAP GITLAB

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

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

Ralf Ulrich's avatar
Ralf Ulrich committed
72 73 74 75 76 77 78 79 80
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:
``` shell
source /opt/rh/devtoolset-9/enable
```

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:
81 82 83

``` shell
pip install --user conan
Ralf Ulrich's avatar
Ralf Ulrich committed
84
```
85

Ralf Ulrich's avatar
Ralf Ulrich committed
86 87
### Compiling

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

90
``` shell
91
git clone --recursive git@gitlab.ikp.kit.edu:AirShowerPhysics/corsika.git
Ralf Ulrich's avatar
Ralf Ulrich committed
92 93
mkdir corsika-build
cd corsika-build
Ralf Ulrich's avatar
Ralf Ulrich committed
94 95 96 97
cmake ../corsika -DCMAKE_INSTALL_PREFIX=../corsika-install
make -j8
make install
```
Ralf Ulrich's avatar
Ralf Ulrich committed
98 99 100 101 102 103 104 105 106 107 108 109 110


## 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
111
```shell
Ralf Ulrich's avatar
Ralf Ulrich committed
112 113 114 115
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
116
cmake ../corsika -DCMAKE_INSTALL_PREFIX=../corsika-install
Ralf Ulrich's avatar
Ralf Ulrich committed
117 118 119 120
make -j8
make install
```

Ralf Ulrich's avatar
Ralf Ulrich committed
121 122 123 124 125 126 127 128
## 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
129

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

132

Ralf Ulrich's avatar
Ralf Ulrich committed
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147
## 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">
148
```
Ralf Ulrich's avatar
Ralf Ulrich committed
149 150 151 152 153 154 155

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

Maximilian Reininghaus's avatar
Maximilian Reininghaus committed
158
Visualize output (needs gnuplot installed): 
Ralf Ulrich's avatar
Ralf Ulrich committed
159 160
```shell
bash $corsika_DIR/share/corsika/tools/plot_tracks.sh tracks.dat 
161 162
firefox tracks.dat.gif 
```
Ralf Ulrich's avatar
Ralf Ulrich committed
163 164
(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
165

Ralf Ulrich's avatar
Ralf Ulrich committed
166 167 168
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
169 170


Hans Dembinski's avatar
Hans Dembinski committed
171 172
### Generating doxygen documentation

Ralf Ulrich's avatar
Ralf Ulrich committed
173 174
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
175
Otherwise, e.g. on Ubuntu 18.04, do:
Ralf Ulrich's avatar
Ralf Ulrich committed
176
```shell
Hans Dembinski's avatar
Hans Dembinski committed
177 178 179
sudo apt-get install doxygen graphviz
```
Switch to the corsika build directory and do
Ralf Ulrich's avatar
Ralf Ulrich committed
180
```shell
Ralf Ulrich's avatar
Ralf Ulrich committed
181
make docs
182
make install
Hans Dembinski's avatar
Hans Dembinski committed
183
```
Ralf Ulrich's avatar
Ralf Ulrich committed
184 185 186
open with firefox:
```shell
firefox ../corsika-install/share/corsika/doc/html/index.html
187
```
Ralf Ulrich's avatar
doxygen  
Ralf Ulrich committed
188