.. toctree::
    :maxdepth: 3

USER GUIDE
==========

Installation
------------

*EASCherSim* is available through `pip <https://pypi.org/project/easchersim/>`_ or `conda <https://anaconda.org/easchersim/easchersim>`_.

.. code-block:: bash

    $ python3 -m pip install easchersim  
    $ conda install -c easchersim easchersim

.. warning:: root is **not** a dependency

.. note:: 
    We recommand the conda install. 
    This allows to easily install root for creating root output files via  
    Information on how to install conda can be found `here <https://docs.conda.io/projects/conda/en/latest/index.html>`_.
    
    .. code-block:: bash

        # create conda enviroment EASCherSim and install package in it
        $ conda create --name EASCherSim  -c easchersim easchersim
        # install root in your environment if wanted
        $ conda activate EASCherSim
        $ conda install -c conda forge root

Usage
-----

.. image:: ../_static/usage_demo.svg

Create a configuration file
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The command line simulator uses store simulation settings in an ini file (read by *configparser*). To
generate a configuration file run the following, with your choice of file name.
To create a configuration file names *my_config_file.ini* and a primary shower energy of *1e18eV*

.. code-block:: bash

   $ easchersim make-config my_config_file.ini -e 1e18

All option can be specified via argument and displayed with the *-h* argument.

.. code-block:: none

    $ easchersim make-config -h

    usage: easchersim make-config [OPTIONS] CONFIGFILE

    OPTIONS:
    -h, --help            show this help message and exit
    --det-alt DET_ALT     Set detection plane altitude in km
    -e ENG, --energy ENG  Set shower energy in eV
    -a ANGLE GEOMETRY-DEF, --angle ANGLE GEOMETRY-DEF
                            Set shower angle and geometry definition (viewing/emergence)
    -d DISTFIRSTINT, --dist-first-int DISTFIRSTINT
                            Set distance to first interaction
    -s {yes,no,on,off}, --scattering {yes,no,on,off}
                            Turn atmospheric scattering on/off
    -m {yes,no,on,off}, --use-mag-field {yes,no,on,off}
                            Turn magnetic field on/off
    -g {yes,no,on,off}, --use-greisen {yes,no,on,off}
                            Use Greisen parametrization for longitudianal profile instead of CORSIKA file
    -o OUTPUT_NAME, --output OUTPUT_NAME
                            Name of the output file. Supported formats are root, npz
    -p {none,basic,general,all}, --plots {none,basic,general,all}
                            Set the type of plots to be created
    --save-plots          Set the type of plots to be created

Run cherenkov simulation
^^^^^^^^^^^^^^^^^^^^^^^^

Simulate cherenkov photons at detection plane and save plots to disk

.. code-block:: bash
    
    $ easchersim run my_config_file.ini --save-plots

Option can be overwritten from the specified configuration file via its command line argument. All available arguments
can be displayed with the *-h* argument

.. code-block:: none

    $ easchersim run -h
    
    usage: easchersim run [OPTIONS] CONFIGFILE

    OPTIONS:
    -h, --help            show this help message and exit
    -e ENG, --energy ENG  Set shower energy in eV
    -a ANGLE GEOMETRY-DEF, --angle ANGLE GEOMETRY-DEF
                            Set shower angle and geometry definition (viewing/emergence)
    -d DISTFIRSTINT, --dist-first-int DISTFIRSTINT
                            Set distance to first interaction
    --save-plots          Set the type of plots to be created

Output files
------------
There are two types of output files that can be generated by EASCherSim. We support the Cern ROOT format as well as 
a the .npz file format to store the simulation results.

.npz format
***********
The .npz file format is a zipped archive of numpy arrays.  
This archive contains the following numpy arrays:

* *shower_prop*: shower properties: energy, viewing angle, distance to first interaction]
* *wavelengths*: wavelength bin edges
* *wavelength_counts*: photon count in each wavelength bin
* *dist_bins*: distance bin edges
* *dist_counts*: photon count in each distance bin
* *time_bins*: timing bin edges
* *time_counts*: photon count per distance bin in each time bin (arr[dist][time])
* *time_offset*: time offset to be added for each distance bin
* *angle_bins*: angular bin edges
* *angle_counts*: photon count per distance bin in each angular bin (arr[dist][ang])
* *angle_offset*: angular offset to be added for each distance bin

Example how to access array from .npz file:

.. code-block:: python
        
    import numpy as np

    npzfile = np.load("outfile.npz")
    npzfile.files
    >>>>['shower_prop', 'wavelengths', 'wavelength_counts', 'dist_bins', 'dist_counts', 'time_bins', 'time_counts', 'time_offset', 'angle_bins', 'angle_counts', 'angle_offset']
        
    npzfile['shower_prop']
    >>>>[1.0e+17 8.5e+01 0.0e+00]

ROOT format
^^^^^^^^^^^
In the ROOT file you can find two TTrees. **cherPhProp** contains the simulation results while **showerProp** holds 
the shower properties (energy, angle and distance to first interaction) used in the simulation.

.. tabs::

    .. code-tab:: bash showerProp

        ******************************************************************************
        *Tree    :showerProp: Shower Properties                                      *
        *Entries :        1 : Total =            2129 bytes  File  Size =        808 *
        *        :          : Tree compression factor =   1.00                       *
        ******************************************************************************
        *Br    0 :energy    : eng/D                                                  *
        *Entries :        1 : Total  Size=        575 bytes  File Size  =         87 *
        *Baskets :        1 : Basket Size=      32000 bytes  Compression=   1.00     *
        *............................................................................*
        *Br    1 :zenith    : zen/D                                                  *
        *Entries :        1 : Total  Size=        575 bytes  File Size  =         87 *
        *Baskets :        1 : Basket Size=      32000 bytes  Compression=   1.00     *
        *............................................................................*
        *Br    2 :startalt  : startalt/D                                             *
        *Entries :        1 : Total  Size=        594 bytes  File Size  =         89 *
        *Baskets :        1 : Basket Size=      32000 bytes  Compression=   1.00     *
        *............................................................................*

    .. code-tab:: bash cherPhProp

        ******************************************************************************
        *Tree    :cherPhProp: Cherenkov Photon Properties                            *
        *Entries :        1 : Total =          756226 bytes  File  Size =     114166 *
        *        :          : Tree compression factor =   6.65                       *
        ******************************************************************************
        *Br    0 :wavelength : TH1D                                                  *
        *Entries :        1 : Total  Size=       2742 bytes  File Size  =       1740 *
        *Baskets :        1 : Basket Size=      32000 bytes  Compression=   1.28     *
        *............................................................................*
        *Br    1 :distance  : TH1D                                                   *
        *Entries :        1 : Total  Size=       2729 bytes  File Size  =       1653 *
        *Baskets :        1 : Basket Size=      32000 bytes  Compression=   1.35     *
        *............................................................................*
        *Br    2 :time_offset : TH1D                                                 *
        *Entries :        1 : Total  Size=       2751 bytes  File Size  =       1684 *
        *Baskets :        1 : Basket Size=      32000 bytes  Compression=   1.33     *
        *............................................................................*
        *Br    3 :angle_offset : TH1D                                                *
        *Entries :        1 : Total  Size=       2759 bytes  File Size  =       1677 *
        *Baskets :        1 : Basket Size=      32000 bytes  Compression=   1.34     *
        *............................................................................*
        *Br    4 :time_dist : vector<TH1D>                                           *
        *Entries :        1 : Total  Size=     372136 bytes  File Size  =      10335 *
        *Baskets :        1 : Basket Size=      32000 bytes  Compression=  35.96     *
        *............................................................................*
        *Br    5 :angle_dist : vector<TH1D>                                          *
        *Entries :        1 : Total  Size=     372438 bytes  File Size  =      96107 *
        *Baskets :        1 : Basket Size=      32000 bytes  Compression=   3.87     *
        *............................................................................*

For the vector variables each entry represents the corresponding distance bin.
Examples of how to read the photon properties and show the distribution for a given distance bin. 
First in C++ syntax and second using pyroot.

.. tabs::

    .. code-tab:: c++
    
        #include "TFile.h
        #include "TH1D.h
        #include "TTreeReader.h
        #include "TTreeReaderValue.h  

        int main(){
            // open TFile in read mode
            TFile* f = TFile::Open("easchersim_result.root");
            // read TTree
            TTreeReader reader("cherPhProp", f);
            // read branch of interest
            TTreeReaderValue<vector<TH1D>> TimeDistVec(reader, "time_dist");
            // get Next event of branch
            reader.Next()
            // draw the timing distribution in first distance bin
            (*TimeDistVec)[0].Draw()
            
            f->Close()
        }
    .. code-tab:: python
        
        import ROOT

        # open TFile in read mode
        f = ROOT.TFile.Open('easchersim_result.root', 'read')
        # read TTree
        t = f.Get("cherPhProp")
        # Get entry
        t.GetEntry(0)
        # Get vector for time dist TH1D (1 vec entry per distance bin)
        vec_time_dist = t.time_dist
        # draw the timing distribution in first distance bin
        vec_time_dist[0].Draw()

        f.Close()
