README.rst

KM3BUU

The KM3BUU project is an integrated environment for the GiBUU particle interaction simulation. 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 KM3NeT Git server first:

git clone https://git.km3net.de/simulation/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 requested, 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 .

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")

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