README.rst

KM3BUU
======

.. image:: https://git.km3net.de/simulation/km3buu/badges/master/pipeline.svg
    :target: https://git.km3net.de/simulation/km3buu/pipelines

.. image:: https://git.km3net.de/simulation/km3buu/badges/master/coverage.svg



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:

.. code-block:: console

   git clone https://git.km3net.de/simulation/km3buu
   cd km3buu

After downloading the repository the package can be installed via:

.. code-block:: console

   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:

.. code-block:: console

   docker run -it --rm docker.km3net.de/simulation/km3buu:latest /bin/bash

or built locally:

.. code-block:: console

   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:

.. code-block:: python3

    >>> 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.

.. code-block:: python3

    >>> from km3buu.ctrl import run_jobcard

    >>> run_jobcard(jc, "./output")
    0

Finally, the output can be parsed using a `GiBUUOutput` object:

.. code-block:: python3

    >>> from km3buu.output import GiBUUOutput

    >>> data = GiBUUOutput("./output")

The event data can further be converted to a pandas dataframe

.. code-block:: python3

    >>> df = data.df

or an awkward array

.. code-block:: python3

    >>> arr = data.arrays