Installation
It is recommended to use the Umami framework with a Docker image.
You can either choose to use a fully build version where you are ready to run the code or a version where you are able to modify the code.
If you are using lxplus or a local cluster with cvmfs
access, the recommended way is to use the images unpacked on cvmfs
as described here. This will just work out of the box.
Docker container#
You can run Umami in a Docker container. This is the most convenient way and ensures that you are not required to install any dependencies as those are already included in the Docker image.
The images are created automatically from the master
branch and updated for every modification using Continuous Integration. Here, the latest
tag on Docker Hub corresponds to the master
branch in the GitLab project. Similarly, the latest-gpu
tag on Docker Hub corresponds to the master
branch but provides additional support for running TensorFlow with GPUs.
Other tags correspond to the tags in the GitLab project. For more details see the image overviews below.
There are three different kind of images:
- Base images
- these image types contain all the necessary dependencies for umami
but not the umami
package itself
- these are best suited for any developemts in umami
- You can browse them here in the gitlab container registry
- Base images plus
- these image types extend the umamibase
image installing additional packages defined in requirements_additional.txt
- these are especially useful for R&D studies requiring additional packages
- Packaged images
- these images use the base images and have umami
installed on top
- these are the best choice if you just want to run umami
but you don't want to change anything in the code
- You can browse them here in the gitlab container registry
Overview Base images
Image tag | Description | gitlab registry |
---|---|---|
latest |
CPU base image from master |
gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:latest |
latest-gpu |
GPU base image from master |
gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:latest-gpu |
latest-pytorch-gpu |
GPU base image from master with pytorch instead of tensorflow |
gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:latest-pytorch-gpu |
0-2 |
CPU base image of tag 0.2 |
gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:0-2 |
0-2-gpu |
GPU base image of tag 0.2 |
gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:0-2-gpu |
0-1 |
CPU base image of tag 0.1 |
gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:0-1 |
0-1-gpu |
GPU base image of tag 0.1 |
gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:0-1-gpu |
not all tags are listed here, please have a look in the gitlab registry for a complete list
Overview BasePlus images
Image tag | Description | gitlab registry |
---|---|---|
latest |
CPU base image from master |
gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase-plus:latest |
latest-gpu |
GPU base image from master |
gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase-plus:latest-gpu |
not all tags are listed here, please have a look in the gitlab registry for a complete list
Overview Packaged images
Image tag | Description | Docker hub | gitlab registry |
---|---|---|---|
latest |
CPU packaged image from master |
btagging/umami:latest | gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami:latest |
latest-gpu |
GPU packaged image from master |
btagging/umami:latest-gpu | gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami:latest-gpu |
latest-pytorch-gpu |
GPU packaged image from master with pytorch instead of tensorflow |
btagging/umami:latest-pytorch-gpu | gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami:latest-pytorch-gpu |
0-2 |
CPU packaged image of tag 0.2 |
btagging/umami:0-2 | gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami:0-2 |
0-2-gpu |
GPU packaged image of tag 0.2 |
btagging/umami:0-2-gpu | gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami:0-2-gpu |
0-1 |
CPU packaged image of tag 0.1 |
btagging/umami:0-1 | gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami:0-1 |
0-1-gpu |
GPU packaged image of tag 0.1 |
btagging/umami:0-1-gpu | gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami:0-1-gpu |
jupyter-develop |
CPU packaged image of tag jupyter-develop |
-- | gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami:jupyter-develop |
not all tags are listed here, please have a look in the gitlab registry for a complete list
Launching containers using Docker (local machine)#
If you work on a local machine with Docker installed, you can run Umami with this command:
docker run --rm -it btagging/umami:latest
You can mount local directories with the -v
argument:
docker run --rm -it -v /cvmfs:/cvmfs -v /afs:/afs -v $PWD:/home/workdir btagging/umami:latest
There is also an image with GPU support, which can significantly speed up the training step assuming your machine has a GPU. You can run Umami image with GPU support using this command:
docker run --rm -it btagging/umami:latest-gpu
Using the base image instead
As mentioned before, if you want to modify the code, please use the Base images which would change your docker command e.g. to
docker run --rm -it gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:latest
Launching containers using Singularity (lxplus/institute cluster)#
If you work on a node of your institute's computing centre or on CERN's lxplus
, you don't have access to Docker.
Instead, you can use singularity, which provides similar features. How to use singularity on lxplus
can be found here
You can run Umami in singularity with the following command:
singularity exec docker://btagging/umami:latest bash
Alternatively, you can retrieve the image from the GitLab container registry
singularity exec docker://gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami:latest bash
Using the base image instead
singularity exec docker://gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:latest
Speeding up loading time of singularity images
The above commands are often slow since they require a new conversion of the docker image to a singularity image. There is a possibility to avoid this by converting them once via
singularity pull <folder_where_you_want_to_store_the_image>/umami_base_cpu.img docker://gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:latest
singularity exec <folder_where_you_want_to_store_the_image>/umami_base_cpu.img bash
Singularity cache and temporary files
By default, singularity
will store the cache in your home directory, which will cause space issues.
You can redirect the persistent cache to another folder via export SINGULARITY_CACHEDIR=<alternative_folder>
which could be for instance the EOS/CERNBox area, instead of home on lxplus
. You will still want to keep the 'temporary' location on (fast) local storage, this is controlled by SINGULARITY_TMPDIR
.
The easiest is to add to your ~/.bashrc
on lxplus
the following lines
export SINGULARITY_CACHEDIR=/eos/user/${USER:0:1}/${USER}/singularity
export SINGULARITY_TMPDIR=/tmp/${USER}/singularity
mkdir -p "${SINGULARITY_TMPDIR}"
mkdir /eos/user/${USER:0:1}/${USER}/singularity
/eos/user
space, you can do that by connecting to https://cernbox.cern.ch
Singularity images on CVMFS#
It is also possible to use the umami
and umamibase-plus
images directly from cvmfs
. If you have a good connection to cvmfs
this will be very fast to use out of the box.
The umamibase-plus
images are located in the folder /cvmfs/unpacked.cern.ch/gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/
. You can use the latest image e.g. via
singularity shell /cvmfs/unpacked.cern.ch/gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase-plus:latest
Available tags
To check which tags are available, you can have a look in the folder via
ls /cvmfs/unpacked.cern.ch/gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/
The umami
images are located in /cvmfs/unpacked.cern.ch/gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/
.
An example usage of the latest
image would be
singularity shell /cvmfs/unpacked.cern.ch/gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami:latest
Available tags
To check which tags are available, you can have a look in the folder via
ls /cvmfs/unpacked.cern.ch/gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/
Launching containers with GPU support using Singularity (lxplus/institute cluster)#
The image with GPU support can be run with the command (note that singularity requires the --nv
argument to provide the GPU resources within the container):
singularity exec --nv docker://btagging/umami:latest-gpu bash
If you work on AFS and want to explicitly state which paths should be made available, consider the --contain
argument and mounting volumes inside the container with the --bind
argument:
singularity exec --contain --nv --bind /afs --bind /cvmfs --bind /eos docker://btagging/umami:latest bash
Using the base image instead
singularity exec --nv docker://gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:latest-gpu bash
Cloning the repository#
As mentioned before, if you plan to modify the code, the best choice are the Base images. How to use images on your local machine or cluster you can see below.
In order to make code changes, you need to clone the repository via
git clone ssh://git@gitlab.cern.ch:7999/atlas-flavor-tagging-tools/algorithms/umami.git
umami
package now accessible in python you need to run
python -m pip install -e .
umami
folder.
Newer singularity versions
On certain clusters Singularity
might be configured such that it is not writable and python -m pip install -e .
will fail. In this case you need to set your PYTHONPATH
to e.g. the current directory (export PYTHONPATH=$PWD:$PYTHONPATH
) and choose a folder e.g. python_install
also as install directory via python -m pip install --prefix python_install -e .
(you first need to create the python_install
folder). It can then also happen that you are getting a weird error with RecursionError: maximum recursion depth exceeded in comparison
, then you need to clean up your repository via rm -rf umami.egg-*
.
This is also bundled in a script you can use
source run_setup.py
Local installation
This option is very much discourraged due to the difficulty of installing tensorflow properly which is handled automatically by the docker containers.
First, retrieve the project by cloning the git repository.
git clone ssh://git@gitlab.cern.ch:7999/atlas-flavor-tagging-tools/algorithms/umami.git
In order for the umami
code to work you need at least python3.8
or higher.
Now you need to install all the requirements which are in the first place tensorflow
.
WARNING: it is typically quite complicated to install tensorflow
properly, especially on a cluster. You might consider using a conda environment for this.
Tensorflow, together with all other requirements can be installed using the provided requirements.txt
file and the following command:
pip install -r requirements.txt
Then, install the project locally.
python -m pip install .
-e
option, which creates a symbolic link to the local directory instead of copying it.
Consequently, any changes you make to the code are directly picked up.
python -m pip install -e .
The requirements.txt
serves as a lock
file, snap-shoting the actual packages installed with their versions. Together with the related hashes, the environment can be exactly rebuild. The process to generate this file is explained in the development part of the documentation.