Installation
============

Installation of the European XFEL Offline Calibration tools is best
done into an anaconda/3 environment using Maxwell_ cluster. However, there are no explicit
dependencies, so any Python3 environment is capable of running the tool.

A more detailed step-by-step instruction can be found in the :ref:`tutorial`.

Package Requirements
--------------------

Requirements can be categorized into three types:

1. Those required to run the the general tool chain,
2. Those required by the notebooks themselves,
3. Those required to run notebooks concurrently on a HPC cluster.

Categories 1+2 are usually Python modules, as given in the `requirements.txt`
file found in the root directory. Additionally, PyDetLib_ is required.
It can be installed either as a Karabo dependency or manually.

Parallel execution is currently supported in a `SLURM_` environment.
However, sequential execution is available using the `--no-cluster-job`
parameter when executing `xfel-calibrate`.

.. _Python: http://www.python.org/
.. _Karabo: https://in.xfel.eu/readthedocs/docs/karabo/en/latest/
.. _SLURM: https://slurm.schedmd.com
.. _PyDetLib: https://in.xfel.eu/readthedocs/docs/pydetlib/en/latest/
.. _Maxwell: https://confluence.desy.de/display/IS/Running+Jobs+on+Maxwell

Installation using Anaconda
---------------------------

First you need to load the anaconda/3 environment through::

    1. module load anaconda/3 

If installing into other python enviroments, this step can be skipped. 

Then the package for the offline calibration can be obtained from the git repository::

    2. git clone https://git.xfel.eu/gitlab/detectors/pycalibration.git

Home directory
++++++++++++++

You can then install all requirements of this tool chain in your home directory by running::

    3. pip install -r requirements.txt . --user

in pycalibration's root directory.

After installation, you should make sure that the home directory is in the PATH environment variable::

    4. PATH=/home/<username>/.local/bin:$PATH

Preferred directory
+++++++++++++++++++

Alternatively, you can install all requirements in a directory of your preference by::

    3. mkdir /gpfs/exfel/data/scratch/<username>/<directory-name>
       pip install --target=/gpfs/exfel/data/scratch/<username>/<directory-name> -r requirements.txt .

and it is important to make sure that the installed requirements are in the PATH environment::

    4. PATH=/gpfs/exfel/data/scratch/<username>/<directory-name>/bin:$PATH


After this make sure that you adjust the :ref:`configuration` and settings in the xfel-calibrate
folder to match your environment.

The tool-chain is then available via the::

    xfel-calibrate
    
command.


Installation using karabo
+++++++++++++++++++++++++

If required, one can install into karabo environment. The difference would be to 
first source activate the karabo envrionment::

    1. source karabo/activate

then after cloning the offline calibration package from git, the requirements can be installed through::

    3. pip install -r requirements.txt .

Development Installation
------------------------

For a development installation in your home directory, which automatically 
picks up (most) changes, first install the dependencies as above, 
but then install the tool-chain separately in development mode::

   pip install -e . --user

.. note:: Using "- -target" for development installation in a preferred directory can lead to errors.

.. note:: For development installation in karabo environment "- -user" is not needed.

Installation of New Notebooks
-----------------------------

To install new, previously untracked notebooks in the home directory, 
repeat the installation of the the tool-chain, without requirments, 
from the package base directory::

    pip install --upgrade . --user
    
Or, in case you are actively developing::

    pip install -e . --user