.. _nuradiomc-interface:

NuRadioMC Interface
===================

.. toctree::
   :titlesonly:

   release_notes

This project provides an interface/reader for NuRadioMC simulations [#]_. It reads the hdf5 files [#]_ produced by NuRadioMC, allows to inject the events generated with NuRadioMC into IceTray and simulated the "optical counterpart" for radio neutrino events. The hdf5 files only contain a subset of information of the radio simulation, in partiular they do _not_ contain any simulated antenna signals (those are stored in a differnt file type). This reader does not read any "station-level" information.

.. [#] : `NuRadioMC documentation <https://nu-radio.github.io/NuRadioMC/main.html>`_
.. [#] : `NuRadioMC hdf5 files <https://nu-radio.github.io/NuRadioMC/NuRadioMC/pages/HDF5_structure.html>`_

Classes
-------

- ``NuRadioMCReader``: Reads HDF5 files and injects particles from the first interaction in a I3MCTree.
- ``EventFilterModule``: Allows filtering events those particles have a chance to reach the volume of the optical detector.
- ``ParticleTypeRecover``: Allows determining lepton flavors when information was not stored in hdf5 for the particular event.

Short summary of hdf5 files
---------------------------

Each row in a dataset (``energy``, ``zenith``, ``azimuth``, ...) refers to a particle shower which produces radio emission. Hence, a single neutrino event can "produce" several entries, i.e., rows, in the hdf5 files because it produces several particle cascades which produce radio emission. The association between shower(s) and event is made with the ``event_group_id``. By default, only events/showers which trigger the radio detector are stored. However, the shower produced in the first/primary interaction (which contains relevant information of the parent neutrino) is always stored (this did not happen for simulations in hdf5 files of version v2.2 due to a bug).

Tests
-----

The file ``test.hdf5`` is a striped version of::

    /data/sim/Gen2/radio/2020/gen2-tdr-2021/simulation_output/secondaries_1700km2/step3/baseline_array/config_ARZ2020_noise/D01detector_sim/mu/mu_18.00eV_0.0_0.1.hdf5

The "station-level" data sets are removed and only the first 100 events kept.