Update docs

CHANGELOG.rst

 Unreleased changes
 ------------------
 
+v1.0.0 - Release Candidate 1
+----------------------------
+* Dockerfile with full GiBUU2021r4 installation (including RootTuple writeout)
+* GiBUU output parser object
+* KM3NeT file write out
+* Runnerscript for std. configuarion (for use with Docker)
+* Fixed header and sec. lepton write out
+* Neutrino jobcard generator with FSI timesteps and particle decay option
+* GiBUU to KM3NeT w2 weight conversion
 * Add decay option to the runner script
 * Add muon propagation and upgrade tau propagation/decay being km3net geometry based
 * Add singularity build and deploy option to KM3NeT FTP to CI

CONTRIBUTING.md

-Contributing
-------------
-
-Do it!

CONTRIBUTING.rst

+You want to hack new features into ``km3buu`` or are just here to fix a
+bug? Here's what you need to know:
+
+If there are any questions please join https://chat.km3net.de and ask in the #software
+or #simulation channel.
+
+For general questions and suggestions please open an issue under:
+
+https://git.km3net.de/simulation/km3buu/-/issues
+
+or if you already have code ready go ahead and please open up and merge request (MR) at:
+
+https://git.km3net.de/simulation/km3buu/-/merge_requests .
+
+In order to get an complete overview over all the issues please also check out:
+
+https://git.km3net.de/simulation/km3buu/-/boards
+
+Feel free to contribute, we appreciate all ideas/suggestions/improvements 
+
+.. raw:: html
+
+   👍

README.rst

@@ -8,89 +8,49 @@ KM3BUU
 
 
 
-The KM3BUU project is an integrated environment for the GiBUU studies
-within the KM3NeT experiment.
+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 python based using ``singularity`` for running GiBUU.
-The python environment is required to have version 3.5 or higher and singularity 
-is required to have version 3.3 or higher (e.g. `v3.4 <https://sylabs.io/guides/3.4/user-guide/>`__). In the default workflow the singularity image is build remote from the 
-KM3NeT docker server, but it can also be built locally (see :ref:`Local Machine`).
-`KM3BUU` is not provided via python package manager and can be installed as follows.
-First the repository needs to be cloned:
+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:
 
-::
-
-   pip install -e . 
-
-GiBUU Only Usage
-~~~~~~~~~~~~~~~~
-The repository design also allows the usage without python environment.
-In this scenario the singularity container containing the GiBUU environment 
-has to be built first. This can be done locally if root privileges are available:
-
-::
+.. code-block:: console
 
-   make build
+   pip install -e
 
-If root privileges are not available, e.g. running the `KM3BUU` on a compute cluster, 
-it also can be done remote via the KM3NeT docker server:
+(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:
 
-   make buildremote
+.. code-block:: console
 
-If the python environment is used afterwards, the file path of the container can
-be written to the configuration file and is not required to be built again.
+   docker run -it --rm docker.km3net.de/simulation/km3buu:latest /bin/bash
 
-For running GiBUU the used jobcards have to be moved to a sub-folder within the 
-jobcards folder of the project. Each sub-folder represents a set of jobcards, 
-which can be passed to GiBUU by:
+or built locally:
 
-::
+.. code-block:: console
 
-   make run CARDSET=examples
-
-This specific command runs all jobcards within the ``jobcards/examples`` folder
-and stores the output inside the folder ``output``. The folder structure
-is applied from the ``jobcards``\ folder.
-
-Theory
-------
-
-In order to retrieve correct results and provide correct KM3NeT weights (w2)
-the treatment of the GiBUU weights is an important step. A brief description 
-of the GiBUU weights and how to calculate actual cross sections is given on the
-`GiBUU Homepage <https://gibuu.hepforge.org/trac/wiki/perWeight>`__ and
-a more detailed description of the calculation can be found in the `PhD Thesis
-of Tina Leitner <https://inspirehep.net/literature/849921>`__ in Chapter 8.3.
-As it is mentioned in the description of the output flux file in the
-`documentation <https://gibuu.hepforge.org/Documentation/code/init/neutrino/initNeutrino_f90.html#robo1685>`__ this is not taken somehow into account inside the weights.
-Following the description the GiBUU event weight can be converted to a binned
-cross section via
+   cd km3buu
+   docker build .
 
-.. math::
-    \frac{d\sigma}{E} = \frac{\sum_{i\in I_\text{bin}} w_i}{\Delta E}\cdot\frac{1}{E\Phi},
 
-where :math:`\Phi`__ is the simulated flux
-As the weights are given for each run individually the weight also has to be divided
-by the number of runs.
 
-Tutorial
---------
-The python framework is build around the GiBUU workflow, i.e. a jobcard is 
-processed and the output files are written out. 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:
+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
 
@@ -98,7 +58,7 @@ this is done via loading an existing jobcard:
 
     >>> jc = read_jobcard("jobcards/examples/example.job")
 
-In the next step the jobcard is processed:
+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
 
@@ -114,3 +74,15 @@ 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
+
+.. code-block:: python3
+
+    >>> df = data.df
+
+or an awkward array
+
+.. code-block:: python3
+
+    >>> arr = data.arrays

doc/contribute.rst

 Contribute
 ==========
 
-You want to hack new features into ``foo`` or are just here to fix a
-bug? Great!
+.. include:: ../CONTRIBUTING.rst

doc/index.rst

@@ -6,14 +6,20 @@
 
     self
 
+Contents
+--------
+
 .. toctree::
     :maxdepth: 2
 
-    user_guide
+    theory
     contribute
     changelog
 
     Code Coverage <https://simulation.pages.km3net.de/km3buu/coverage>
     Source (Git) <https://git.km3net.de/simulation/km3buu>
 
+Indices and tables
+------------------
+
 * :ref:`genindex`

doc/theory.rst

+Theory
+======
+In the following section specific parts of `km3buu` are described which
+exceed the functionaliy of GiBUU and are important for the usage.
+
+Kinematic variables
+-------------------
+Some additional variables which characterise the interaction are
+calculated inside `km3buu`.
+
+.. list-table:: Kinematic Variables
+   :widths: 50 50
+   :header-rows: 1
+
+   * - Variable
+     - Content
+   * - Bjorken scaling variable :math:`B_x`
+     - :math:`Q^2 / 2p\cdot q` where :math:`p` is the momentum given by GiBUU
+   * - Energy fraction passed to hadr. system / :math:`B_y`
+     - :math:`p\cdot q / p\cdot k`
+   * - Momentum passed to the hadronic system / :math:`Q^2`
+     - :math:`(k_{\nu}-k_{lepton})^2`
+
+Weights
+-------
+In order to retrieve correct results and provide correct KM3NeT weights (w2)
+the treatment of the GiBUU weights is an important step. A brief description
+of the GiBUU weights and how to calculate actual cross sections is given on the
+`GiBUU Homepage <https://gibuu.hepforge.org/trac/wiki/perWeight>`__ and
+a more detailed description of the calculation can be found in the `PhD Thesis
+of Tina Leitner <https://inspirehep.net/literature/849921>`__ in Chapter 8.3.
+As it is mentioned in the description of the output flux file in the
+`documentation <https://gibuu.hepforge.org/Documentation/code/init/neutrino/initNeutrino_f90.html#robo1685>`__ this is not taken somehow into account inside the weights.
+Following the description the GiBUU event weight can be converted to a binned
+cross section via
+
+.. math::
+    \frac{d\sigma}{E} = \frac{\sum_{i\in I_\text{bin}} w_i}{\Delta E}\cdot\frac{1}{E\Phi},
+
+where :math:`\Phi` is the simulated flux.
+As the weights are given for each run individually the weight also has to be divided
+by the number of runs.
+
+Free Particle Cuts
+------------------
+The secondary (pertubative) particles are not filter with respect to their energy
+and bound to the nuclear potential. This violates the energy conservation of the
+system and may lead to unphysical result. Therefore a particle mask is
+provided by the `GiBUUOutput` object in order to check the
+energy-momentum relation of the contained nucleons, d.h. :math:`pdgid {\epsilon} [2112,2212]`),
+for the rest mass. If this is :math:`m_p<m_0` the particle is rejected in the given mask.

doc/user_guide.rst

-User GUide
-==========
-
-Install ``km3buu`` and have fun!

km3buu/cmd.py

@@ -2,6 +2,48 @@
 # coding=utf-8
 # Filename: cmd.py
 # Author: Johannes Schumann <jschumann@km3net.de>
+"""
+Runscript for GIBUU/KM3BUU
+
+options:
+  -h, --help            show this help message and exit
+  --events EVENTS, -n EVENTS
+                        Number of events which are simulated
+  --multifile MULTIFILE, -m MULTIFILE
+                        How many km3net files to write from the dataset
+  --seed SEED, -s SEED  Seed which should be used for the (pseudo) random number gen.
+  --flavor {electron,muon,tau}, -f {electron,muon,tau}
+                        Simulated neutrino flavor
+  --interaction {nc,cc,antinc,anticc}, -i {nc,cc,antinc,anticc}
+                        The current type of the weak interaction
+  --target A Z, -t A Z  The number of nucleons/protons in the target nucleus
+  --timesteps TIMESTEPS, -x TIMESTEPS
+                        The number of timesteps performed by GiBUU
+  --geometry {no,can,sphere,cylindrical}, -g {no,can,sphere,cylindrical}
+                        Type of detector enviroment geometry should be used
+  --center x y z, -c x y z
+                        Center (offset) if a geometry is used (otherwise ignored)
+  --dimensions [DIMENSIONS ...], -d [DIMENSIONS ...]
+                        Dimensions of the geometry; sphere -> -d <radius> / can -> -d <radius> <zmin> <zmax> / cylindrical -> -d
+                        <seawaterheight> <rockheight> <radius> <canradius> <canzmin> <canzmax>
+  --output-dir OUTPUT, -o OUTPUT
+                        Output directory
+  --run RUNNUMBER, -r RUNNUMBER
+                        Run number to use
+  --gibuuparams GIBUUPARAMS, -p GIBUUPARAMS
+                        JSON file for modified GiBUU namelist params
+  --taupropagation, --no-taupropagation
+                        Do tau propagation (default: False)
+  --decay, --no-decay   Decay final state particles (according to the decays done in gSeaGen) (default: True)
+  --zenith cosZmin cosZmax, -z cosZmin cosZmax
+                        Zenith range of the direction if a geometry is used
+
+modes:
+  {single,range}        Modes
+    single              Run in single energy mode
+    range               Run in energy range mode
+
+"""
 
 import numpy as np
 import argparse