Offline analysis
================

.. highlight:: console

JupyterHub
----------

To configure and use the JupyterHub on Maxwell cluster with the CAS provided
karabo_data package, follow `jupyter_karabo_data doc`_. It also contains an
example notebook on how to use karabo_data to process the DAQ recorded data.

.. _jupyter_karabo_data doc: https://git.xfel.eu/gitlab/zhujun/my_notebooks

Then visit to `max-jhub`_ and start a server on the EXFEL partition.

.. _max-jhub: https://max-jhub.desy.de

To connect from outside the desy network, open a tunnel::

  ssh -L 127.0.0.1:4443:max-jhub.desy.de:443 desyusername@max-display.desy.de

then open locally the webpage `tunneled-max-jhub`_.

.. _tunneled-max-jhub: https://127.0.0.1:4443

Maxwell console
---------------

Initial Setup
~~~~~~~~~~~~~

Offline analysis can be done on the maxwell cluster with jupyter but some things
needs to be setup before. First of all, ssh to maxwell::

    ssh desyusername@max-exfl

There we need to edit your shell config file so that .local/bin is added to your
path. That will allow use to upgrade some python packages. To edit, lauch::

    nano ~/.zshrc

and add the following line, replacing desyusername::

    export PATH=/home/desyusername/.local/bin/:$PATH

at the end of the file. Save it and relog.

Then upgrade `pip` for yourself and install some CAS analysis package with::

    module add anaconda/3
    pip3 install --user --upgrade pip
    pip3 install --user karabo_data
    pip3 install --user --upgrade ipykernel


Reserving node for interactive processing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To perform interactive work on maxwell, we need to reserve a node four ourselves
for some time. We ssh to maxwell and reserve a node with salloc. The salloc -t
options let us specify the duration for which we need the node. By default it's
one hour. Here we define 0-8 which means 0 days and 8 hours::

    ssh desyusername@max-exfl
    salloc -N 1 -p exfel -t 0-8
    salloc: Granted job allocation 1284776
    salloc: Waiting for resource configuration
    salloc: Nodes max-exfl026 are ready for job

The salloc tells us which node is reseverd, here max-exfl026. So we now ssh to
that particular node in another terminal. We use -X option of ssh such that
jupyter can open the browser through the ssh connection::

    ssh -X max-exfl026
    module add anaconda/3
    jupyter notebook

CAS analysis package: karabo_data
---------------------------------

Information on using the 'karabo_data' software package from CAS can be found at
`karabo_data doc`_.

.. _karabo_data doc: https://karabo-data.readthedocs.io/en/latest/

Moving run data to offline storage
----------------------------------

To process the run data on the maxwell offline cluster, it is first necessary to
move them there. This is done via the `Metadata`_ service by indicating that a
particular run is 'Good' and can be saved for long term purposes and moved to
maxwell.

.. _Metadata: https://in.xfel.eu/metadata/