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.

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:

$ 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):

$ 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).

$ 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:

$ 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

$ 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. Refer to the Docker Documentation 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. SLURM job example) or you can simply run a python session inside the container

$ 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:

$ 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.

$ 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).