Introduction#
README#
,-.----. ,--.das nd ____ ulticore utils for corsik 7
\ / \ ,---, ,--.'| ,---, ,' , `. ,---,
| : \ ' .' \ ,--,: : | ' .' \ ,-+-,.' _ | ' .' \
| | .\ : / ; '. ,`--.'`| ' : / ; '. ,-+-. ; , || / ; '.
. : |: |: : \ | : : | |: : \ ,--.'|' | ;| : : \
| | \ :: | /\ \ : | \ | :: | /\ \ | | ,', | ': : | /\ \
| : . /| : ' ;. : | : ' '; || : ' ;. : | | / | | || | : ' ;. :
; | |`-' | | ;/ \ \' ' ;. ;| | ;/ \ \' | : | : |, | | ;/ \ \
| | ; ' : | \ \ ,'| | | \ |' : | \ \ ,'; . | ; |--' ' : | \ \ ,'
: ' | | | ' '--' ' : | ; .'| | ' '--' | : | | , | | ' '--'
: : : | : : | | '`--' | : : | : ' |/ | : :
| | : | | ,' ' : | | | ,' ; | |`-' | | ,'
`---'.| `--'' ; |.' `--'' | ;/ `--''
`---` '---' '---'
PANAMA - A python toolkit for CORSIKA7.
Features#
This python package provides multiple features – each feature can be used independently, but they also work great together.
Execute CORSIKA7 on multiple cores
Read CORSIKA7 DAT files (“particle files”) to pandas DataFrames
Correctly parse output from the
EHISToption
Calculate weights for a multiple primary spectra
To see some examples on how to use panama, see the introduction in the documentation. To get an overview of how the features play together, have a look at the example notebook in the documentation. In-depth explanation is provided in the API documentation.
Installation#
pip install corsika-panama
If you want to convert Corsikas DAT files to HDF5 files, you need to install the optional hdf dependency
pip install corsika-panama[hdf]
CORSIKA7#
For usage and installation of CORSIKA7, please refer to its website and its userguide. To properly use this package, knowledge of CORSIKA7 is required.
If you want to install CORSIKA7, you need to request access to their CORSIKA7 mailing list, as described on their website, then you will receive the CORSIKA7
password.
If you want to skip the process of getting familiar with the software and compiling it with coconut, panama provides a (linux) script for compiling
it.
You will need a fortran compiler. CORSIKA7 will then be pre-configured with the curved earth, EHIST, SIBYLL2.3d and URQDM options.
For finer control over the used options, please compile CORSIKA7 yourself.
After cloning this repository, you can then execute
CORSIKA_VERSION=77500 CORSIKA_PW=CORSIKA_PASSWORD_YOU_WILL_RECEIVE_BY_MAIL admin/download_corsika.sh
which will download and compile CORSIKA7 version 77500.
If you are interested in automatically testing software using CORSIKA7, using GitHub actions,
have a look at the .github folder of this project in combination with the admin script.
Contributing#
Contributions and suggestions are very welcome.
Feel free to open an issue or pull request.
This project uses pdm for the build system as well as a
dependency and virtual environment manager.
For suggestions on how to set up a development environment, have a look at CONTRIBUTING.md.
Further Notes#
This project tries to stay compatible with the suggestions from Scikit hep.
Naming idea goes back to @Jean1995, thanks for that! He originally proposed “PArallel ruN of corsikA on MAny cores”, as the scope of this library grew bigger, it evolved into the current name.
This started as part of the code I wrote for my master thesis. I ended in the same place where most CORSIKA7 users end when running large CORSIKA7 simulations and wrote small scripts to split one simulation request into multiple CORSIKA7 processes with different seeds. The FACT software (fact-project/corsika_wrapper) and the IceCube software does essentially the same thing (and I am sure, MAGIC, CTA and other air-shower based observatories do the same). I hope this package provides a more experiment-independent and better documented version of internal software packages.
Quick Examples#
Run CORSIKA7 on multiple cores#
You need to have CORSIKA7 installed to run this.
Running 100 showers on 4 cores with primary being proton:
$ panama run --corsika path/to/corsika7/executable -j4 ./tests/files/example_corsika.template
83%|████████████████████████████████████████████████████▋ | 83.0/100 [00:13<00:02, 6.36shower/s]
Jobs should be nearly finished, now we wait for them to exit
All jobs terminated, cleanup now
Injecting 5 different primaries (Proton, Helium-4, Carbon-12, Silicon-28, Iron-54 roughly aligning with grouping in H3a) with each primary shower taking 10 jobs:
$ panama run --corsika corsika-77420/run/corsika77420Linux_SIBYLL_urqmd --jobs 10 --primary ""{2212: 500, 1000020040: 250, 1000060120: 50, 1000140280: 50, 1000260540: 50}"" ./tests/files/example_corsika.template
,-.----. ,--.das nd ____ ulticore utils for corsik 7
\ / \ ,---, ,--.'| ,---, ,' , `. ,---,
| : \ ' .' \ ,--,: : | ' .' \ ,-+-,.' _ | ' .' \
| | .\ : / ; '. ,`--.'`| ' : / ; '. ,-+-. ; , || / ; '.
. : |: |: : \ | : : | |: : \ ,--.'|' | ;| : : \
| | \ :: | /\ \ : | \ | :: | /\ \ | | ,', | ': : | /\ \
| : . /| : ' ;. : | : ' '; || : ' ;. : | | / | | || | : ' ;. :
; | |`-' | | ;/ \ \' ' ;. ;| | ;/ \ \' | : | : |, | | ;/ \ \
| | ; ' : | \ \ ,'| | | \ |' : | \ \ ,'; . | ; |--' ' : | \ \ ,'
: ' | | | ' '--' ' : | ; .'| | ' '--' | : | | , | | ' '--'
: : : | : : | | '`--' | : : | : ' |/ | : :
| | : | | ,' ' : | | | ,' ; | |`-' | | ,'
`---'.| `--'' ; |.' `--'' | ;/ `--''
`---` '---' '---' v0.7.2
...
Read CORSIKA7 DAT files to pandas dataframes#
Example: Calculate mean energy in the corsika files created in the example above:
In [1]: import panama as pn
In [2]: run_header, event_header, particles = pn.read_DAT(glob="corsika_output/DAT*")
100%|████████████████████████████████████████████████████████████| 2000/2000.0 [00:00<00:00, 10127.45it/s]
In [3]: particles["energy"].mean()
Out[3]: 26525.611020413744
run_header, event_header and particles are all pandas.DataFrames and can conveniently be used.
If CORSIKA7 is compiled with the EHIST option, then the mother particles are automatically deleted, by default (this behaviour can be changed withdrop_mothers=False).
If you want additional columns in the real particles storing the mother information use mother_columns=True.
Convert CORSIKA7 DAT files to hdf5 files#
For this you need to have PyTables installed.
You can do that if via pip install corsika-panama[hdf].
$ panama hdf5 path/to/corsika/dat/files/DAT* output.hdf5
The data is available under the run_header event_header and particles key.
Weighting to primary spectrum#
This packages also provides facility to add a weight column to the dataframe, so you can look at corsika-output
in physical flux in terms of $(\mathrm{m^2} \mathrm{s}\ \mathrm{sr}\ \mathrm{GeV})^{-1}$.
Using the example above, to get the whole physical flux in the complete simulated energy region:
In [1]: import panama as pn
In [2]: run_header, event_header, particles = pn.read_DAT(glob="corsika_output/DAT*")
100%|████████████████████████████████████████████████████████████| 2000/2000.0 [00:00<00:00, 10127.45it/s]
In [3]: particles["weight"] = pn.get_weights(run_header, event_header, particles)
In [4]: particles["weight"].sum()*(run_header["energy_max"]-run_header["energy_min"])
Out[4]:
run_number
1.0 1234.693481
0.0 1234.693481
3.0 1234.693481
2.0 1234.693481
dtype: float32
Which is in units of $(\mathrm{m^2}\ \mathrm{s}\ \mathrm{sr})^{-1}$. We get a result for each run, since in theory we could have different energy regions. Here, we do not, so the result is always equal.
Weighting can be applied to different primaries, also, if they are known by the flux model.
add_weight can also be applied to dataframes loaded in from hdf5 files produced with PANAMA.