Tutorial.md

+# CORSIKA 8 Tutorial – instructions
+
+These instructions guide you through the process of obtaining a working CORSIKA 8 executable working as a replacement of CORSIKA 7.xy. Two options are discussed: Either you build and run CORSIKA 8 via apptainer[<sup>1</sup>](#sdfootnote1sym), or you build directly on your own system. The latter option is more flexible, but requires more manual steps and you might run into pitfalls since we cannot test every combination of possible operating system/distribution, installed packages, etc.
+
+Note that we do not consider the version we provide right now as ready for productive use. On a short timescale (days/weeks), we plan to include FLUKA as default low-energy hadronic interaction model, which is considerably more stable and much faster than the current default UrQMD.
+
+## Option A: Build via apptainer
+
+1. Download the file c8tutorial.def from the indico page
+2. Build the container:\
+   apptainer build --sandbox c8tutorial c8tutorial.def
+
+You can now run corsika from within the container via
+
+apptainer exec --writable c8tutorial corsika --help
+
+Note that we use --sandbox and --writable here just to be able to save the PROPOSAL tables. Otherwise they would have to be created each time you run corsika.
+
+## Option B: Build directly on your system
+
+### Required tools for building
+
+**cmake**<span dir="">: install via system’s package manager or pip</span>
+
+**conan**<span dir="">: </span>pip3 install --user conan==1.60
+
+Make sure they are inside your $PATH!\
+→ export PATH=$PATH:$HOME/.local/bin
+
+And. of course, you need a reasonably recent compiler suite, either **gcc/g++/gfortran** or **clang/clang++/gfortran**<span dir="">.</span>
+
+### Download & build CORSIKA 8
+
+1. clone CORSIKA 8:\
+   git clone --recursive --depth 1 ↵\
+   https://gitlab.iap.kit.edu/AirShowerPhysics/corsika.git
+2. create build directory (anywhere you want, here: same level as source repo)\
+   mkdir corsika-build
+3. install dependencies via conan:\
+   corsika/conan-install.sh ./corsika-build
+4. build C8 with inside build directory, pointing to source directory\
+   cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ↵\
+   \-S ./corsika -B ./corsika-build\
+   cd ./corsika-build\
+   make -j4\
+   (if you’re impatient, abort when building the tests…)
+
+You have the "framework" part ready to go. Let’s now build main executable:
+
+1. go back to top-level directory\
+   cd ..
+2. compile **corsika**\
+   cmake -Dcorsika_DIR=$PWD/corsika-build -S ↵\
+   ./corsika/examples -B ./corsika-build-examples
+3. cd ./corsika-build-examples\
+   make corsika
+
+Make yourself familiar with bin/corsika (help -h) and run a shower! Most likely PROPOSAL needs to generate tables, which takes \~10-30 min. Additional tables will be generated whenever you use the --emcut option with a value not used before.
+
+Example: corsika --pdg 2212 -E 1e5 -f shower_proton_2 --emcut=0.01 --emthin=1e-4
+
+\
+Python library
+
+Now install CORSIKA 8 Python library and some other useful ones. This is not strictly required – you can also read .parquet files directly e.g. with pandas.
+
+1. pip install –user ↵\
+   'git+https://gitlab.iap.kit.edu/AirShowerPhysics/corsika.git#subdirectory=python'
+2. For the tutorial notebook, you need (besides jupyter-lab)\
+   pip install --user boost_histogram mplhep pandas particle
+
+<div>
+
+[1](#sdfootnote1anc)https://apptainer.org/; formerly known as _singularity_
+
+</div>
\ No newline at end of file