This lesson is being piloted (Beta version)

Setting up the ATLAS Environment


Teaching: 30 min
Exercises: 30 min
  • What is a “release”?

  • How can I configure my laptop to use “ATLAS code”?

  • Setup your working environment with Docker

  • Load the ATLAS release through an image

Setting up “ATLAS”

Your collaborators in ATLAS produce a lot of amazing and powerful code that allows you to perform complex tasks and carry out amazing analyses. This code is generally referred to as “athena”. You can browse this code by clicking on the previous link. However, to be able to use this code you have to “get access” to it. This is done by building a basic version of athena and producing a bunch of libraries and header files which are subsequently bundled into what is referred to as a release.

You will learn much more about the structure of this release when we learn about CMake on the second day of the workshop. However, for now, you can view this “release” as a pre-requisite to be able to write code to analyze ATLAS data (and Monte Carlo simulation!).

There are a few ways to get access to this pre-compiled codebase. For the majority of this workshop we will be using Docker to do this and working in an AnalysisBase release container. You will learn more about the details of Docker on Thursday of the workshop and what is presented here is only the minimal setup which will allow you to work through the tutorial.

Installing Docker

General information about Docker and details of installation can be found here: Docker Installation Depending on the operating system you are using on the local machine, links to specific instructions on the Docker website can be found below.

It is highly recommended that you DO NOT use Windows. Few individuals use this OS within the HEP community as most tools are designed for Unix-based systems. If you do have a Windows machine, consider making your computer a dual-boot machine - Link to Directions

Download Docker for Windows instructions.

Docker Desktop for Windows is the Community Edition (CE) of Docker for Microsoft Windows. To download Docker Desktop for Windows, head to Docker Hub.

Please read the relevant information on these pages, it should take no more than 5 minutes.

Download Docker for MacOS instructions.

Docker is a full development platform for creating containerized apps, and Docker Desktop for Mac is the best way to get started with Docker on a Mac. To download Docker Desktop for MacOS, head to Docker Hub.

Please read the relevant information on these pages, it should take no more than 5 minutes.
Another common way to install packages on Mac OSX is via the homebrew package manager. In the case of docker, you can easily install docker by setting up homebrew and executing brew cask install docker.

Downloading and installing Docker for Linux may be slightly more difficult but please contact the organisers or tutors as soon as possible so they can help with any problems.

Here are the instructions for two popular Linux distributions:

  • CentOS
  • Ubuntu

  • Instructions for other Linux distributions can be found on the Docker docs pages.

    Be sure to read the Docker documentation on post-installation steps for Linux and managing Docker as a non-root user. This will allow you to edit files when you have started up the Docker container from your image.

    If something doesn’t work

    Docker is a standard industry tool. The directions above should “just work”. That said, if you spend one hour working by yourself and still find that you are having issues with the basic setup, ASK SOMEONE!!! We have created a mattermost channel (Link to Mattermost Channel) where you can dynamically ask tutors and other participants questions. This pertains to setting up Docker as well as every other portion of the bootcamp.

    And more broadly, this is a very good general rule of thumb to get into. If you are struggling with something, particularly if it is technical, don’t needlessly waste your time thinking that “this is a stupid question, so I’m not allowed to ask”. There will be something to help you and that is what collaboration is all about anyways. So do one of the following :

    • Ask the person sitting next to you
    • Ask that helpful person on your analysis team or working group
    • Ask a skype channel or mattermost chat
    • Ask a mailing list

    When you are done, just be sure to say “thank you”. #teamworkmakesthedreamwork

    Download an ATLAS AnalysisBase Release

    Start by downloading the Docker image for the release you want using the docker pull. The Docker images get managed by Docker behind the scenes (Again, more details in the Docker session), so you don’t have to worry about that yourself:

    docker pull atlas/analysisbase:21.2.75

    The image should be around 4GB in size, so make sure you have the space available on your hard drive.

    Latest Release

    These instructions will use a numbered release, which should be your default to work with.

    If you want to use the absolutely latest, bleeding edge version you can replace atlas/analysisbase:21.2.75 with atlas/analysisbase or atlas/analysisbase/latest. However, doing so is not recommended for this bootcamp. Though some times it can be fun to live on the edge, so go ahead, try to pull the very latest ATLAS AnalysisBase image.

    Starting the Release

    Let’s now test to see whether this worked. Now that you have pulled the release image, you can use it to setup the ATLAS environment release. This is done using the docker run command.

    docker run --rm -it atlas/analysisbase:21.2.75 bash

    This will change the look of command prompt and you should now see bash][atlas]:~ > as your prompt. If you list the files in this directory, you should see one file called Sourcing this file will load the release that is contained within the image. Try is


    If this worked properly and you have setup docker correctly, then you should see the following

    [bash][atlas]:~ > source
    Configured GCC from: /opt/lcg/gcc/6.2.0binutils/x86_64-slc6
    Configured AnalysisBase from: /usr/AnalysisBase/21.2.75/InstallArea/x86_64-slc6-gcc62-opt
    [bash][atlas AnalysisBase-21.2.75]:~ >

    The CVMFS Way

    One other common way to setup the analysis release is to use the CernVM File System which is available on nearly all clusters within the collaboration. In this case, you use the setupATLAS alias command to initialize the asetup (“athena(a) setup”) command which is subsequently used to create the surrounding ATLAS coding environment by giving you access to the precompiled base release. This would typically look something like

    -bash-4.2$ setupATLAS
    lsetup               lsetup <tool1> [ <tool2> ...] (see lsetup -h):
     lsetup agis          ATLAS Grid Information System
     lsetup asetup        (or asetup) to setup an Athena release
     lsetup atlantis      Atlantis: event display
    -bash-4.2$ asetup AnalysisBase,21.2.75,here
    Using AnalysisBase/21.2.75 [cmake] with platform x86_64-slc6-gcc62-opt
      at /cvmfs/
    Test area: /afs/

    This is achieving precisely the same goal as what we are achieving with Docker in this bootcamp. The primary benefit is that using Docker allows you to comfortably use your laptop for all of your work. So, cluster down? (No Problem!), poor internet connection? (No Problem), … you can now work all the time!

    Key Points

    • A software release (e.g. AnalysisBase) is necessary to analyze ATLAS data.

    • You will learn much more about the details of an ATLAS release on Tuesday!

    • Docker will serve as the “portal” for all ATLAS work throughout this tutorial. It can be thought of a “virtual machine”.

    • You will learn much more about Docker on Thursday!