diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index cb947afa64333e31b766ae28ad153915498e5daf..d25e9e45d980be79c54bd96a54dcabf3bc39d5f8 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -1,6 +1,15 @@
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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
deleted file mode 100644
index d900199a131b24b2e6885bcee2caa4a2a73aaed6..0000000000000000000000000000000000000000
--- a/CONTRIBUTING.md
+++ /dev/null
@@ -1,4 +0,0 @@
-Contributing
-------------
-
-Do it!
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
new file mode 100644
index 0000000000000000000000000000000000000000..bf1785d4d9e1cf8cee72b7611e19dc6fea499ce6
--- /dev/null
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,23 @@
+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
+
+ 👍
diff --git a/README.rst b/README.rst
index 8a891bdad4b73329b8e145add7a10d82f64010d8..cf62fa8d3417cf948689ee1d866175d1b95546c2 100644
--- a/README.rst
+++ b/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
diff --git a/doc/contribute.rst b/doc/contribute.rst
index 19b90657d8a6a212534c71c9c023f5eef097f58a..3d2a51a56c89b8fe793021a778dfec3d231d3ff2 100644
--- a/doc/contribute.rst
+++ b/doc/contribute.rst
@@ -1,5 +1,4 @@
Contribute
==========
-You want to hack new features into ``foo`` or are just here to fix a
-bug? Great!
+.. include:: ../CONTRIBUTING.rst
diff --git a/doc/index.rst b/doc/index.rst
index 87e20a8f1a1a055d0758d2028b4e1aba55488c28..32d7e3e110b63b55ee7227a9bc91270e67a26e13 100644
--- a/doc/index.rst
+++ b/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`
diff --git a/doc/theory.rst b/doc/theory.rst
new file mode 100644
index 0000000000000000000000000000000000000000..353933191d4f3490733b3ebac631828b334d1b0c
--- /dev/null
+++ b/doc/theory.rst
@@ -0,0 +1,51 @@
+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.
diff --git a/doc/user_guide.rst b/doc/user_guide.rst
deleted file mode 100644
index 47a9ee63dbb8d214f660d0060c280589cbcc347a..0000000000000000000000000000000000000000
--- a/doc/user_guide.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-User GUide
-==========
-
-Install ``km3buu`` and have fun!
diff --git a/km3buu/cmd.py b/km3buu/cmd.py
index 7bc40a092834e50ff73248f9b6a0d60c81a4d9b9..ffe8afe13f78c091c3bf93e17805317f87381519 100755
--- a/km3buu/cmd.py
+++ b/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