.. _installation-page:

************
Installation
************

There are various ways for the installation of ``cait``, which are outlined in the following. We provide stable releases on PyPI, whose source is hosted on the GitLab/GitHub master branch, as well as a development version. In the development version, some new features might still be unstable. It does, however, include all cutting-edge and current implementations.
Our recommendation is to use the latest version from PyPI, but we highly appreciate curious users of the development version, who report bugs via the Gitlab/Github issue tracker.

.. note::
  **Important Note for JupyterHub on computing clusters**

  In the past, many users experienced issues with our interactive plotting tools which are based on ``plotly`` and ``ipywidgets``. These problems were due to version mismatches between the ``plotly``/``ipywidgets`` packages and their corresponding JupyterLab extensions (which are automatically installed alongside the packages). 

  To not run into such issues in the first place, we recommend one of the following approaches:

  * Whenever possible, you should **run the cait JupyterHub container** on your computing cluster directly, as it works out of the box.
  * If you cannot/don't want (for whatever reason) to use the container, you can install ``cait`` in the base environment of your computing cluster's JupyterLab. This is more likely to work right away, but we don't recommend to do so.
  * To keep things tidy, you should install it in a virtual environment (see below), but you will have to make sure that the same ``plotly``/``ipywidgets`` versions (which are installed as dependencies of ``cait``) are also present in the base environment (because that's where your JupyterHub is running from). A good practice to ensure this is to always pip-upgrade ``plotly``/``ipywidgets`` to the latest version in both environments. Note that you will potentially have to match these versions every time you upgrade ``cait``.

  Lastly, remember to **restart JupyterHub completely** (not just the kernel) for the changes to take effect.

  To learn how to add a virtual environment as a kernel to jupyterlab, refer to `this great reference <https://janakiev.com/blog/jupyter-virtual-envs/>`_.

.. note::
    **Installation in virtual environments**

    We recommend to install ``cait`` in a separate environment together with a clean installation of ``jupyter-lab`` (for interactive analysis) to avoid version conflicts of dependencies:

    .. code:: console

        $ python3 -m venv venv_cait
        $ source venv_cait/bin/activate
        $ python -m pip install —-upgrade pip
        $ python -m pip install jupyterlab
        $ deactivate
        $ source venv_cait/bin/activate
        $ python -m pip install cait
        $ deactivate
        $ source venv_cait/bin/activate
        $ jupyter-lab

    If you want, you can add the newly created virtual environment as a kernel for jupyter (such that you don't have to do the last two lines above, i.e. always activate the environment):

    .. code:: console

        $ source venv_cait/bin/activate
        $ python -m pip install ipykernel
        $ python -m ipykernel install --name=venv_cait

    You can now choose the kernel in ``jupyter-lab``, VS code, etc.

Installation from PyPI
====================================

``cait`` is hosted on the Python package index (PyPI).

.. code:: console

    $ python -m pip install cait

For older or unreleased version, use the installation from Git.

There are some additional dependencies which can be installed together with ``cait`` using the following syntax:

.. code:: console

    $ pyton -m pip install cait[<opt_dep1>, <opt_dep2>]

- ``remfiles``: Also install libraries needed to access remote files, most prominently using the 'XRootD' protocol.
- ``nn``: Install neural network dependencies which are not installed by default to keep Cait more light-weight.
- ``clplot``: If you are one of the few people who want to get the 'uniplot' backend for 'cait.versatile' plotting classes, use this optional dependency to unlock command line plotting.
- ``test``: Install 'pytest' to run tests.
- ``docs``: Install dependencies for building docs with ``sphinx``.

Pre-built Docker containers
====================================
For people who have access to the CERN GitLab, the easiest way to get a container is

.. code:: console

    $ singularity pull --docker-login docker://gitlab-registry.cern.ch/cryocluster/cait:<tag>

where ``tag`` could be ``develop`` or any (tagged) release. For each tag, there is a regular and a ``-slim`` version, where ``-slim`` does not include 'heavy' dependencies like ``torch`` and is therefore smaller in size.
If you do not have access to the CERN GitLab, the docker container can be built with this `Dockerfile <https://github.com/fewagner/cait/blob/develop/Dockerfile>`_. Refer to the `Docker Documentation <https://docs.docker.com/build/concepts/dockerfile/>`_ on how to use it. Note that we use ``singularity`` to pull and run the container, even though it has been built using Docker. This works and is just a matter of preference.

You can use this container e.g. for cluster jobs (see e.g. :ref:`slurm-example-section`) or you can simply run a python session inside the container

.. code:: console

    $ singularity run cait_develop.sif

Furthermore, many computing clusters offer the possibility to start **JupyterHub from a custom singularity image**. The container provided above can be used for that purpose as well.

Options for developers
======================

As a developer of ``cait``, it's best if you clone the repository and make an *editable installation*:

.. code:: console

    $ git clone https://gitlab.cern.ch/cryocluster/cait.git
    $ python -m pip install -e cait/

A full copy/paste for installing Cait from the repository (cleanly and reproducably in a virtual environment) is given in the following. We also directly check out the development branch for the most up-to-date features.

.. code:: console

    $ mkdir CAIT
    $ cd CAIT
    $ git clone https://gitlab.cern.ch/cryocluster/cait.git
    $ python3 -m venv venv_cait
    $ source venv_cait/bin/activate
    $ python -m pip install —-upgrade pip
    $ python -m pip install jupyterlab
    $ deactivate
    $ source venv_cait/bin/activate
    $ python -m pip install -e cait/
    $ deactivate
    $ source venv_cait/bin/activate
    $ python -m pip install ipykernel
    $ python -m ipykernel install --name=venv_cait
    $ deactivate
    $ cd cait
    $ git checkout develop

Deactivating/activating the environment all the time makes sure that the latest changes are recognized by jupyter (and all interactive widgets are properly installed).