OrcaNet: A training organizer for Deep Learning in KM3NeT
=========================================================

.. image:: https://badge.fury.io/py/orcanet.svg
    :target: https://badge.fury.io/py/orcanet

.. image:: https://git.km3net.de/ml/OrcaNet/badges/master/pipeline.svg
    :target: https://git.km3net.de/ml/OrcaNet/pipelines

.. image:: https://git.km3net.de/examples/km3badges/-/raw/master/docs-latest-brightgreen.svg
    :target: https://ml.pages.km3net.de/OrcaNet

.. image:: https://git.km3net.de/ml/OrcaNet/badges/master/coverage.svg
    :target: https://ml.pages.km3net.de/OrcaNet/coverage


OrcaNet is a deep learning framework based on tensorflow in order to simplify the
training process of neural networks for astroparticle physics, in particular
for Orca, Arca and Antares. It incorporates
automated logging, plotting and validating during the training, as well as
saving and continuing the training process. Additionally, it features easy 
management of multiple neural network inputs and the use of training data 
which is split over multiple files.

In this sense, it tackles many challenges that are usually found in 
astroparticle physics, like huge datasets.

Documentation is at https://ml.pages.km3net.de/OrcaNet/.

OrcaNet is a part of the Deep Learning efforts for the neutrino telescope KM3NeT.
Find more information about KM3NeT on http://www.km3net.org .

OrcaNet is currently being developed at the official KM3NeT gitlab (https://git.km3net.de/ml/OrcaNet).

However, there's also a github mirror that can be found at https://github.com/ViaFerrata/OrcaNet.

Past studies
------------

For studies done using orcanet, check out the wiki page of the machine learning
working group https://wiki.km3net.de/index.php/Machine_Learning_working_group .
You can find orcanet config files used in studies in the directory
orcanet_contrib/configs of the orcanet repo.


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

OrcaNet can be installed via pip by running::

    pip install orcanet


In order to make use of tensorflow's GPU acceleration, you need cuda and
cudnn installed. You can see which of these each tensorflow version needs here
https://www.tensorflow.org/install/source#gpu


Containerization
----------------
The easiest way to run OrcaNet is with singularity.
A Singularity image of the latest stable version of OrcaNet with tensorflow
and cuda/cudnn for GPUs
is automatically uploaded to our sftp server.
Download it e.g. via::

    wget http://sftp.km3net.de/singularity/orcanet_v???.sif

where v??? is the version, e.g. orcanet_v1.0.1.sif.
Run it on a CPU e.g. via::

    singularity shell orcanet_v???.sif

If you run it on a GPU, don't forget the nv flag::

    singularity shell --nv orcanet_v???.sif

