README.rst

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