Input files for `grrr`
======================

This folder contains the input files for the `grrr` code. This document
describes briefly how to run `grrr` with this input and produce the
simulation results described in the paper

*Evaluation of Monte Carlo tools for high energy atmospheric physics*, C. Rutjes, D. Sarria, A. B. Skeltved4, A. Luque, G. Diniz, N. Ostgaard and U. Ebert, submitted to Geoscientific Model Development (2016).

For more details, please contact [A. Luque](mailto:aluque@iaa.es), who wrote the
`grrr` code and prepared these input files.


Setting up `grrr`
-----------------

You can download the `grrr` code from its [main
repository](https://github.com/aluque/grrr). The simulations in the
paper were produced with the commit tagged HEAP (hash
[`3886b58b68e5da359babb66906bde3be9883b307`](https://github.com/aluque/grrr/tree/3886b58b68e5da359babb66906bde3be9883b307)).

`grrr` is mostly written in Python but the time-critical parts are
written in a C library that you have to compile. You can do it with:

    make

This will produce a file named `libgrrr.so` that will be loaded at
runtime. Therefore it must be visible to your dynamic linker. In a Linux
system you can make sure that this is the case by setting
`LD_LIBRARY_PATH`:

    export LD_LIBRARY_PATH=path/to/grrr

In a Mac OS X system change that to:

    export DYLD_LIBRARY_PATH=path/to/grrr

Note that `grrr` requires at least Python 3.0 and a few Python
libraries: numpy, scipy, matplotlib, h5py, and PyYAML.


Using the input files
---------------------

All input files in this folder have name such as:

    grrr_electrons_NXXXX_EYYYY[_ZZ]_f.yaml

where

> -   *XXXX* is the number of initial particles.
> -   *YYYY* is the primary energy in electronvolts (eV).
> -   *ZZ* is an index for simulations that are split up into several
>     smaller simulations. In these cases *XXXX* is the nomber of
>     *total* particles, adding all simulations with different *ZZ*.

You can run `grrr` with one of the input files with:

    python /path/to/grrr/runner.py grrr_electrons_NXXXX_EYYYY[_ZZ]_f.yaml

Once the simulation is completed it will produce a file named:

    grrr_electrons_NXXXX_EYYYY[_ZZ]_f.h5


Processing output
-----------------

Once all the `.h5` files are produced, one has to extract from them the
information about particle properties at each of the successive
detectors. This can be done with the Python script `extract.py` provided
in this folder and invoked as:

    python extract.py infile.h5 -o outfile.txt [-f] [-b]

where the `-f` flag is used to count only forward-advancing particles
and `-b` is currently deprecated. To process all `.h5` files resulting
from the input files in this folder we provide the script `process.sh`,
which can be invoked as:

    . process.sh

This will produce the files:

    grrr_electrons_NXXXX_EYYYY_f.txt

containing all data analyzed in the paper.


Re-generating input files
-------------------------

**Note:** *This steps are not needed to reproduce the data used in the paper:
the provided input files are enough for that.  These steps are required only
if you wish to use different parameter sets. *

The input files described above were generated from the template
`electrons_tmpl.yaml`, where the placeholders `${...}` are replaced by the
corresponding value for each parameter set.  This is performed by invoking

    python mkinput.py

The script `mkinput.py` relies on `cases.py` to determine the parameter sets
(primary energies, detector locations etc.).

