Commit a8db3114 authored by toschroe's avatar toschroe
Browse files
parents c966827a b958fbe0
Pipeline #3283139 failed with stages
in 19 seconds
......@@ -32,6 +32,7 @@ checking_mr:
script:
- python pipelines/gitlab-check-mr.py
linter:
stage: linting
image: python:3.7-slim
......@@ -56,78 +57,9 @@ yaml_linter:
- if: $CI_COMMIT_BRANCH != ''
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
test_coverage:
stage: coverage_test_stage
image: python:3.7-slim
script:
- pip install --upgrade pip setuptools wheel
- pip install pytest==6.2.4
- pip install pytest-cov==2.12.0
- cd ./coverage_files/
- coverage combine
- coverage report
- coverage xml
- coverage html
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_PROJECT_PATH=="atlas-flavor-tagging-tools/algorithms/umami" && '$CI_MERGE_REQUEST_LABELS !~ /Skip-CI/'
artifacts:
when: always
paths:
- coverage_files/
reports:
cobertura: coverage_files/coverage.xml
retry: 2
coverage_html_report:
stage: builds
image: gitlab-registry.cern.ch/ci-tools/ci-web-deployer
script:
- deploy-eos
needs:
- test_coverage
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PROJECT_PATH=="atlas-flavor-tagging-tools/algorithms/umami"
variables:
EOS_PATH: "/eos/user/u/umamibot/www/coverage_reports/master/"
CI_OUTPUT_DIR: "coverage_files/htmlcov/"
METHOD: rsync
- if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_PROJECT_PATH=="atlas-flavor-tagging-tools/algorithms/umami" && '$CI_MERGE_REQUEST_LABELS !~ /Skip-CI/'
variables:
EOS_PATH: "/eos/user/u/umamibot/www/coverage_reports/${CI_MERGE_REQUEST_IID}/"
CI_OUTPUT_DIR: "coverage_files/htmlcov/"
METHOD: rsync
test_coverage_post_report:
stage: publish
image: python:3.7-slim
needs: ["test_coverage"]
before_script:
- pip install --upgrade pip setuptools wheel
- pip install python-gitlab
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_PROJECT_PATH=="atlas-flavor-tagging-tools/algorithms/umami" && '$CI_MERGE_REQUEST_LABELS !~ /Skip-CI/'
script:
- python pipelines/gitlab-mr-coverage-api-post.py
pages:
image: python:3.8-alpine
stage: pages
script:
- apk add --no-cache git subversion
- pip install --upgrade pip setuptools wheel
- pip install mkdocs==${MKDOCS_VERSION} mkdocs-material==${MATERIAL_VERSION} mkdocs-static-i18n==${I18NSTATIC_VERSION}
- mkdocs build -d public
- if [[ -f _redirects ]]; then cp _redirects public; fi;
artifacts:
paths:
- public
expire_in: 1 hour
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PROJECT_PATH=="atlas-flavor-tagging-tools/algorithms/umami"
when: always
include:
- 'pipelines/.unit_test-gitlab-ci.yaml'
- 'pipelines/.docker-gitlab-ci.yaml'
- 'pipelines/.integration_test-gitlab-ci.yaml'
- 'pipelines/.coverage-gitlab-ci.yaml'
- 'pipelines/.deployment-gitlab-ci.yaml'
......@@ -24,22 +24,22 @@ After all the files are ready we can start with the training. The config file fo
```yaml
# Set modelname and path to Pflow preprocessing config file
model_name: dips_lr_0.001_bs_15000_epoch_200_nTrainJets_Full
preprocess_config: <path>/<to>/<umami>/umami/examples/PFlow-Preprocessing.yaml
model_name: <MODELNAME>
preprocess_config: <path>/<to>/<preprocessing>/<config>/PFlow-Preprocessing.yaml
# Add here a pretrained model to start with.
# Leave empty for a fresh start
model_file:
# Add training file
train_file: <path>/<to>/<preprocessed>/<samples>/train_file.h5
train_file: <path>/<to>/<train>/<samples>/train_file.h5
# Add validation files
# ttbar val
validation_file: <path>/<to>/<preprocessed>/<samples>/ttbar_validation_file.h5
validation_file: <path>/<to>/<validation>/<samples>/ttbar_r21_validation_file.h5
# zprime val
add_validation_file: <path>/<to>/<preprocessed>/<samples>/zpext_validation_file.h5
add_validation_file: <path>/<to>/<validation>/<samples>/zpext_r21_validation_file.h5
ttbar_test_files:
ttbar_r21:
......@@ -60,12 +60,15 @@ zpext_test_files:
data_set_name: "zpext_r22"
# Path to Variable dict used in preprocessing
var_dict: <path>/<to>/<umami>/umami/umami/configs/Dips_Variables.yaml
var_dict: <path>/<to>/<variables>/Dips_Variables.yaml
exclude: []
# Values for the neural network
NN_structure:
# Decide, which tagger is used
tagger: "dips"
# NN Training parameters
lr: 0.001
batch_size: 15000
......@@ -94,6 +97,9 @@ NN_structure:
# Structure of the dense layers after summing up the track outputs
dense_sizes: [100, 100, 100, 30]
# Options for the Learning Rate reducer
LRR: True
# Eval parameters for validation evaluation while training
Eval_parameters_validation:
# Number of jets used for validation
......@@ -122,36 +128,33 @@ Eval_parameters_validation:
}
# Cuts which are applied to the different datasets used for evaluation
variable_cuts: {
"ttbar_r21": {
"pt_btagJes": {
"operator": "<=",
"condition": 250000,
}
},
"ttbar_r22": {
"pt_btagJes": {
"operator": "<=",
"condition": 250000,
}
},
"zpext_r21": {
"pt_btagJes": {
"operator": ">",
"condition": 250000,
}
},
"zpext_r22": {
"pt_btagJes": {
"operator": ">",
"condition": 250000,
}
},
}
variable_cuts:
ttbar_r21:
- pt_btagJes:
operator: "<="
condition: 250000
ttbar_r22:
- pt_btagJes:
operator: "<="
condition: 250000
zpext_r21:
- pt_btagJes:
operator: ">"
condition: 250000
zpext_r22:
- pt_btagJes:
operator: ">"
condition: 250000
# Working point used in the evaluation
WP: 0.77
# Decide, if the Saliency maps are calculated or not.
Calculate_Saliency: True
# Plotting settings for training metrics plots
Plotting_settings:
......@@ -183,6 +186,7 @@ The different options are briefly explained here:
| `var_dict` | String | Necessary | Path to the variable dict used in the `preprocess_config` to produce the train sample. |
| `exclude` | List | Necessary | List of variables that are excluded from training. Only compatible with DL1r training. To include all, just give an empty list. |
| `NN_structure` | None | Necessary | A dict where all important information for the training are defined. |
| `tagger` | String | Necessary | Name of the tagger that is used/to be trained. |
| `lr` | Float | Necessary | Learning rate which is used for training. |
| `batch_size` | Int | Necessary | Batch size which is used for training. |
| `epochs` | Int | Necessary | Number of epochs of the training. |
......@@ -193,6 +197,14 @@ The different options are briefly explained here:
| `Batch_Normalisation` | Bool | Necessary | Decide, if batch normalisation is used in the _ϕ_ network. |
| `ppm_sizes` | List | Necessary | List of nodes per layer of the _ϕ_ network. Every entry is one layer. The numbers need to be ints! |
| `dense_sizes` | List | Necessary | List of nodes per layer of the _F_ network. Every entry is one layer. The numbers need to be ints! |
| `LRR` | Bool | Optional | Decide, if a Learning Rate Reducer (LRR) is used or not. If yes, the following options can be added. |
| `LRR_monitor` | String | Optional | Quantity to be monitored. Default: "loss" |
| `LRR_factor` | Float | Optional | Factor by which the learning rate will be reduced. `new_lr = lr * factor`. Default: 0.8 |
| `LRR_patience` | Int | Optional | Number of epochs with no improvement after which learning rate will be reduced. Default: 3 |
| `LRR_verbose` | Int | Optional | 0: Quiet, 1: Update messages. Default: 1 |
| `LRR_mode` | String | Optional | One of `{"auto", "min", "max"}`. In "min" mode, the learning rate will be reduced when the quantity monitored has stopped decreasing; in "max" mode it will be reduced when the quantity monitored has stopped increasing; in "auto" mode, the direction is automatically inferred from the name of the monitored quantity. Default: "auto" |
| `LRR_cooldown` | Int | Optional | Number of epochs to wait before resuming normal operation after lr has been reduced. Default: 5 |
| `LRR_min_lr` | Float | Optional | Lower bound on the learning rate. Default: 0.000001 |
| `Eval_parameters_validation` | None | Necessary | A dict where all important information for the training are defined. |
| `n_jets` | Int | Necessary | Number of jets used for evaluation. This should not be to high, due to the fact that Callback function also uses this amount of jets after each epoch for validation. |
| `tagger` | List | Necessary | List of taggers used for comparison. This needs to be a list of string or a single string. The name of the taggers must be same as in the evaluation file. For example, if the DL1d probabilities in the test samples are called `DL1dLoose20210607_pb`, the name you need to add to the list is `DL1dLoose20210607`. |
......@@ -200,6 +212,7 @@ The different options are briefly explained here:
| `frac_values` | Dict | Necessary | Dict with the fraction values for the freshly trained tagger. For all flavour (except the main flavour), you need to add values here which add up to one. |
| `variable_cuts` | Dict | Necessary | Dict of cuts which are applied when loading the different test files. Only jet variables can be cut on. |
| `WP` | Float | Necessary | Working point which is used in the validation and evaluation. |
| `Calculate_Saliency` | Bool | Optional | Decide, if the saliency maps are calculated or not. This takes a lot of time and resources! |
| `Plotting_settings` | None | Necessary | Plotting settings for the validation plots which are produced by the [plotting_epoch_performance.py](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/umami/plotting_epoch_performance.py) script. |
| `UseAtlasTag` | Bool | Necessary | Decide, if the ATLAS tag is printed at the top left of the plot. |
| `AtlasTag` | String | Necessary | Main ATLAS tag which is right to "ATLAS" |
......@@ -225,7 +238,7 @@ This script sets the python path to a specific folder where the executables are
After that, you can switch to the folder `umami/umami` and run the training, using the following command
```bash
train_Dips.py -c ${EXAMPLES}/Dips-PFlow-Training-config.yaml
train.py -c ${EXAMPLES}/Dips-PFlow-Training-config.yaml
```
The results after each epoch will be saved to the `umami/umami/MODELNAME/` folder. The modelname is the name defined in the [Dips-PFlow-Training-config.yaml](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/examples/Dips-PFlow-Training-config.yaml).
......@@ -233,13 +246,13 @@ The results after each epoch will be saved to the `umami/umami/MODELNAME/` folde
If you want instant performance checks of the model after each epoch during the training, you can use
```bash
plotting_epoch_performance.py -c ${EXAMPLES}/Dips-PFlow-Training-config.yaml --dips
plotting_epoch_performance.py -c ${EXAMPLES}/Dips-PFlow-Training-config.yaml
```
which will write out plots for the not- main flavour rejections, accuracy and loss per epoch to `umami/umami/MODELNAME/plots/`. The `--dips` option defines that the DIPS tagger is used. In this form, the performance measurements, like the rejection performances, will be recalculated using the working point, the `frac_values` and the number of validation jets defined in the [Dips-PFlow-Training-config.yaml](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/examples/Dips-PFlow-Training-config.yaml). If you don't want to recalculate it, you can give the path to the existing dict with the option `--dict`. For example:
which will write out plots for the not- main flavour rejections, accuracy and loss per epoch to `umami/umami/MODELNAME/plots/`. In this form, the performance measurements, like the rejection performances, will be recalculated using the working point, the `frac_values` and the number of validation jets defined in the [Dips-PFlow-Training-config.yaml](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/examples/Dips-PFlow-Training-config.yaml). If you don't want to recalculate it, you can give the path to the existing dict with the option `--dict`. For example:
```bash
plotting_epoch_performance.py -c ${EXAMPLES}/Dips-PFlow-Training-config.yaml --dips --dict dips_Loose_lr_0.001_bs_15000_epoch_200_nTrainJets_Full/validation_WP0p77_fc0p018_300000jets_Dict.json
plotting_epoch_performance.py -c ${EXAMPLES}/Dips-PFlow-Training-config.yaml --dict dips_Loose_lr_0.001_bs_15000_epoch_200_nTrainJets_Full/validation_WP0p77_fc0p018_300000jets_Dict.json
```
### Train on Zeuthen Cluster
......@@ -257,8 +270,8 @@ The job will output a log to the current working directory and copy the results
After the training is over, the different epochs can be evaluated with ROC plots, output scores, saliency maps and confusion matrices etc. using the build-in scripts. Before plotting these, the model needs to be evaluated using the [evaluate_model.py](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/umami/evaluate_model.py).
```bash
evaluate_model.py -c ${EXAMPLES}/Dips-PFlow-Training-config.yaml --dips -e 5
evaluate_model.py -c ${EXAMPLES}/Dips-PFlow-Training-config.yaml -e 5
```
The `-e` options (here `5`) allows to set the training epoch which should be evaluated. The `--dips` option defines that the DIPS tagger is used.
The `-e` options (here `5`) allows to set the training epoch which should be evaluated.
It will produce .h5 and .pkl files with the evaluations which will be saved in the model folder in an extra folder called `results/`. After, the [plotting_umami.py](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/umami/plotting_umami.py) script can be used to plot the results. For an explanation, look in the [plotting_umami documentation](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/docs/plotting_umami.md)
# Explaining the importance of features with SHAPley
[SHAPley](https://github.com/slundberg/shap) is a framework that helps you understand how your training of a machine learning model is affected by the input variables, or in other words from which variables your model possibly learns the most. You just need to add a `--shapley` flag to `evaluate_model.py --dl1` as e.g.
[SHAPley](https://github.com/slundberg/shap) is a framework that helps you understand how your training of a machine learning model is affected by the input variables, or in other words from which variables your model possibly learns the most. You just need to add a `--shapley` flag to `evaluate_model.py --tagger dl1` as e.g.
```bash
python umami/evaluate_model.py -c examples/DL1r-PFlow-Training-config.yaml -e 230 --dl1 --shapley
python umami/evaluate_model.py -c examples/DL1r-PFlow-Training-config.yaml -e 230 --tagger dl1 --shapley
```
and it will output a beeswarm plot into `modelname/plots/`. Each dot in this plot is for one whole set of features (or one jet). They are stacked vertically once there is no space horizontally anymore to indicate density. The colormap tells you what the actual value was that entered the model. The Shap value is basically calculated by removing features, letting the model make a prediction and then observe what would happen if you introduce features again to your prediction. If you do this over all possible combinations you get estimates of a features impact to your model. This is what the x-axis (SHAP value) tells you: the on average(!) contribution of a variable to an output node you are interested in (default is the output node for b-jets). In practice, large magnitudes (which is also what these plots are ordered by default in umami) are great, as they give the model a better possibility to discriminate. Features with large negative shap values therefore will help the model to better reject, whereas features with large positive shap values helps the model to learn that these are most probably jets from the category of interest. If you want to know more about shapley values, here is a [talk](https://indico.cern.ch/event/1071129/#4-shapely-for-nn-input-ranking) from our alorithms meeting.
You have some options to play with in the `Eval_parameters_validation` section in the [DL1r-PFlow-Training-config.yaml](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/examples/DL1r-PFlow-Training-config.yaml)
```bash
```yaml
Eval_parameters_validation:
(...other stuff...)
......
......@@ -61,32 +61,38 @@ Eval_parameters_validation:
}
# Cuts which are applied to the different datasets used for evaluation
variable_cuts: {
"ttbar_r21": {
"pt_btagJes": {
"operator": "<=",
"condition": 250000,
}
},
"ttbar_r22": {
"pt_btagJes": {
"operator": "<=",
"condition": 250000,
}
},
"zpext_r21": {
"pt_btagJes": {
"operator": ">",
"condition": 250000,
}
},
"zpext_r22": {
"pt_btagJes": {
"operator": ">",
"condition": 250000,
}
},
}
variable_cuts:
ttbar_r21:
- pt_btagJes:
operator: "<="
condition: 250000
ttbar_r22:
- pt_btagJes:
operator: "<="
condition: 250000
zpext_r21:
- pt_btagJes:
operator: ">"
condition: 250000
zpext_r22:
- pt_btagJes:
operator: ">"
condition: 250000
# Plotting settings for training metrics plots
Plotting_settings:
# Enable/Disable atlas tag
UseAtlasTag: True
# fc_value and WP_b are autmoatically added to the plot label
AtlasTag: "Internal Simulation"
SecondTag: "\n$\\sqrt{s}=13$ TeV, PFlow jets"
# Set the datatype of the plots
plot_datatype: "pdf"
```
| Options | Data Type | Necessary/Optional | Explanation |
......
......@@ -50,20 +50,133 @@ pre-commit install
This will run `isort`, `black` and `flake8` on staged python files when commiting.
## Global Configuration
## General good coding practices
There is a [global configuration](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/umami/configs/global_config.yaml) file which allows to set different global settings.
In the following we are listing some good code practices, we are asking to follow when making merge requests to the repository.
| Option | Description |
|--------|-------------|
| `pTvariable` | Setting the name of the `pT` variable which is used in several places. |
| `etavariable` | Setting the name of the `absolute eta` variable which is used in several places. |
| `DebugLevel` | Defines the debug level. Possible values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
| `TFDebugLevel` | Defines the debug level of tensorflow, it takes integer values [0,1,2,3], where 0 prints all messages. |
## Commenting your Code
If you write new code for Umami, please keep in mind to comment your code properly. It is very hard to understand what you are doing something and why you are doing it. Please keep this in mind! This will make it easier to revise your code.
To make the framework modular, new code that is repeated should be written in a function. When defining a function, please provide a proper doc string and type of the input variables. For example:
```python
def LoadJetsFromFile(
filepath: str,
class_labels: list,
nJets: int,
variables: list = None,
cut_vars_dict: dict = None,
print_logger: bool = True,
):
"""
Load jets from file. Only jets from classes in class_labels are returned.
Input:
- filepath: Path to the .h5 file with the jets.
- class_labels: List of class labels which are used.
- nJets: Number of jets to load.
- variables: Variables which are loaded.
- cut_vars_dict: Variable cuts that are applied when loading the jets.
- print_logger: Decide if the number of jets loaded from the file is printed.
Output:
- Jets: The jets as numpy ndarray
- Umami_labels: The internal class label for each jet. Corresponds with the
index of the class label in class_labels.
"""
```
### Unit/Integration Tests
If you contribute to Umami, please keep in mind that all code should be tested by unit- and integration tests. Normally, the integration test will cover small changes in the pipeline directly, but unit test should be added for all new functions added! Please make sure that all cases of the new functions are tested!
### Readability of numbers
To make large number better readable, please use a `_` to separate them (typically the thousand separator) which was introduced in python 3.6 [PEP515](https://www.python.org/dev/peps/pep-0515/#literal-grammar).
For examle instead of `6728339` please use `6_728_339`.
### Usage of Generators
Often it is more useful to use a generator in the code than returning the values in the loop. You can find examples [here](https://wiki.python.org/moin/Generators) stating *The performance improvement from the use of generators is the result of the lazy (on demand) generation of values, which translates to lower memory usage* and a selection is given below.
```python
def first_n(n):
'''Build and return a list'''
num, nums = 0, []
while num < n:
nums.append(num)
num += 1
return nums
sum_of_first_n = sum(first_n(1_000_000))
```
```python
# a generator that yields items instead of returning a list
def firstn(n):
num = 0
while num < n:
yield num
num += 1
sum_of_first_n = sum(firstn(1_000_000))
```
In the same philosophy there is also list and dict comprehension, here such an example
```python
# list comprehension
doubles = [2 * n for n in range(50)]
# same as a generator
doubles = (2 * n for n in range(50))
# dictionary comprehension
dict_variable = {key:value for (key,value) in dictonary.items()}
```
### f-Strings
Since Python 3.6 the so-called f-strings were introduced providing a powerful syntax for string manipulation. Nice examples and explnations can be found [here](https://realpython.com/python-f-strings/). Try to avoid `str.format()` and `%-formatting` whenever possible, especially for a better readability of the code.
A simple example
```python
nJets = 2_300
jet_collection = "EMPFlow"
info_text = f"We are using the {jet_collection} jet collection and have {nJets} available."
## arbitrary operations
info_text_event = f"We are using the {jet_collection} jet collection and have {nJets * 4} available."
```
### Integer division
In Python 3 a dedicated integer division was introduced.
```python
# standard division -> returns by default a flaot (no rounding)
nEvents = nJets / 4
# integer division -> rounds to integer precision
nEvents = nJets // 4
```
### Type declaration in functions
For a better readablility it is often useful to declare the object type in a function as well as the return type of a function.
Instead of this function
```python
def GetNumberOfEvents(nJets, avg_nJets_per_event=4.3):
return nJets * avg_nJets_per_event
```
## Logging
The umami framework has a custom logging module defined in [umami/configuration/Configuration.py](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/umami/configuration/Configuration.py). To make use of the module you need to import it via
it would look like this
```python
def GetNumberOfEvents(nJets: int, avg_nJets_per_event: float=4.3) -> float:
return nJets * avg_nJets_per_event
```
### Logging
The umami framework has a custom logging module defined in [umami/configuration/Configuration.py](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/umami/configuration/Configuration.py). Do not use the `print()` function but rather the logging. To make use of the module you need to import it via
```python
from umami.configuration import logger
```
......@@ -83,3 +196,17 @@ All logging levels are defined in the following table
| INFO | 20 |
| DEBUG | 10 |
| NOTSET | 0 |
## Global Configuration
There is a [global configuration](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/-/blob/master/umami/configs/global_config.yaml) file which allows to set different global settings.
| Option | Description |
|--------|-------------|
| `pTvariable` | Setting the name of the `pT` variable which is used in several places. |
| `etavariable` | Setting the name of the `absolute eta` variable which is used in several places. |
| `DebugLevel` | Defines the debug level. Possible values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
| `TFDebugLevel` | Defines the debug level of tensorflow, it takes integer values [0,1,2,3], where 0 prints all messages. |
## Installation
It is recommended to use the Umami framework with a Docker image.
The Umami framework can be installed either locally or be run by using 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.
Below, both options are outlined.
### Local installation
First, retrieve the project by cloning the git repository. Then, install the project locally.
## Docker container
You can run Umami in a [Docker container](https://www.docker.com/resources/what-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.
```bash
git clone --recursive ssh://git@gitlab.cern.ch:7999/atlas-flavor-tagging-tools/algorithms/umami.git
The images are created automatically from the `master` branch and updated for every modification using Continuous Integration. Here, the `latest` tag on [Docker Hub](https://hub.docker.com/r/btagging/umami) 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.
python setup.py install
```
There are two 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](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/container_registry/8906) in the gitlab container registry
- 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](https://gitlab.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/container_registry/8387) in the gitlab container registry
Alternatively, if you want to develop the code, use the `develop` install command, 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.
```bash
python setup.py develop
```
??? info "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|
??? info "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|
On certain clusters `Singularity` might be configured such that it is not writable and `python setup.py develop` will fail. In this case you need to set your `PYTHONPATH` to e.g. the current directory (`export PYTHONPATH=$PWD:$PYTHONPATH`) and choose the current folder also as install directory via `python setup.py develop --install-dir .`. 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-*`.
### Docker container
You can run Umami in a [Docker container](https://www.docker.com/resources/what-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.
#### Launching containers using Docker (local machine)
### Launching containers using Docker (local machine)
If you work on a local machine with Docker installed, you can run Umami with this command:
```bash
docker run --rm -it btagging/umami:latest
......@@ -48,9 +67,15 @@ You can run Umami image with GPU support using this command:
docker run --rm -it btagging/umami:latest-gpu
```
#### Launching containers using Singularity (lxplus/institute cluster)
???+ info "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
```bash
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](https://sylabs.io/guides/3.7/user-guide/introduction.html), which provides similar features.
Instead, you can use [singularity](https://sylabs.io/guides/3.7/user-guide/introduction.html), which provides similar features. How to use singularity on `lxplus` can be found [here](https://hsf-training.github.io/hsf-training-docker/10-singularity/index.html)
You can run Umami in singularity with the following command:
```bash
......@@ -62,7 +87,25 @@ 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
```
#### Launching containers with GPU support using Singularity (lxplus/institute cluster)
???+ info "Using the base image instead"
```bash
singularity exec docker://gitlab-registry.cern.ch/atlas-flavor-tagging-tools/algorithms/umami/umamibase:latest
```