KM3BUU¶
This is NOT an official KM3NeT software package.
The KM3BUU project is an integrated python framework for wrapping the GiBUU particle interaction simulation https://gibuu.hepforge.org/trac/wiki . It is specifically designed for studies within the KM3NeT experiment and focuses on the neutrino simulation functionality of GiBUU.
The main code repository can be found at: https://git.km3net.de/simulation/km3buu
The framework covers all parts of the GiBUU workflow, which includes setting up the simulation configuarion inside a so-called jobcarb, running GiBUU and parsing the output files.
Installation¶
The main KM3BUU project is a python based framework, which can be used with a local GiBUU installation or used within a docker container. In order to install the km3buu python module the repository has to be retreived from the Git server first.
From KM3NeT GitLab:
git clone https://git.km3net.de/simulation/km3buu
cd km3buu
From GitHub:
git clone https://github.com/KM3NeT/km3buu
cd km3buu
After downloading the repository the package can be installed via:
pip install -e
(Up to now KM3BUU is not provided via python package manager.)
If working inside a docker environment is recommended, the KM3BUU image can be copied&run directly from the KM3NeT docker server:
docker run -it --rm docker.km3net.de/simulation/km3buu:latest /bin/bash
or built locally:
cd km3buu
docker build .
The docker image contains the latest release of km3buu as well as the GiBUU 2021 Patch 4 (release from 2023-03-23) including RootTuple extension is installed (km3buu v1.0.0).
Getting started¶
The GiBUU workflow starts from a jobcard which contains the configuration which should be simulated. The jobcards are technically FORTRAN namelists and can be created using a Jobcard object. In the example this is done via loading an existing jobcard:
>>> from km3buu.jobcard import Jobcard, read_jobcard
>>> jc = read_jobcard("jobcards/examples/example.job")
Alternatively a neutrino jobcard can be generated from scratch via
>>> from km3buu.jobcard import Jobcard, generate_neutrino_jobcard
>>> generate_neutrino_jobcard(1000, 1, "CC", "muon", (1,10))
This jobcard is subsequently forwarded to GiBUU via the run_jobcard function. The second argument takes a directory which should be used to write out all the output files generated by GiBUU.
>>> from km3buu.ctrl import run_jobcard
>>> run_jobcard(jc, "./output")
0
Finally, the output can be parsed using a GiBUUOutput object:
>>> from km3buu.output import GiBUUOutput
>>> data = GiBUUOutput("./output")
The event data can further be converted to a pandas dataframe
>>> df = data.df
or an awkward array
>>> arr = data.arrays