Skip to content

Prerequisites

This tutorial focuses on development for Athena, so assumes some basic knowledge. In order to get the most out of the tutorial, please read and follow the prerequisites list below. All of the links are taken from the HSF training centre; there is lots of other useful training material there as well so do have a look!

  • You should be familiar with common ATLAS concepts including the data preparation and processing chain, data formats, simulated data preparation &c. Please review the material in the latest analysis tutorial if you are new to ATLAS or need to refresh your knowledge;
  • The tutorial assumes basic C++ knowledge. Please follow the HSF C++ course if you need a refresher. Note that the material in the "essentials" part should be sufficient for this tutorial;
  • Similarly you should be acquainted with Python which is used for configuration: follow this software carpentry Python course to refresh your skills;
  • The tutorial will demonstrate how ATLAS uses Git for software development, but having some basic Git knowledge will be an advantage, so follow this short software carpentry course for the basics;
  • Similarly we will cover how ATLAS uses CMake but it will be useful to follow this CMake course from the HSF.

Setting up before the tutorial

Our aim for the tutorial is that for most of the exercises you'll be able to use your own resources - either directly on your laptop or remotely to your institute cluster. We will also use LXPLUS for some exercises, so everyone should ensure they can use LXPLUS in addition to their own machine.

All attendees to the tutorial need to bring their own laptop either to run on directly or to connect to your institute/LXPLUS. It can be Linux, Mac or Windows, with the first two of these being the most convenient. Before doing anything else you need to make sure that it has the following:

  • A terminal application for remote connections (Linux/Macs have this by default)
  • A text editor or IDE such as VSCode (vi/vim or Emacs within a terminal is also fine).

Testing LXPLUS

This will only work if you have a CERN computing account. Open a terminal and do 

ssh username@lxplus.cern.ch
setupATLAS
asetup Athena,main,latest

If this works your LXPLUS account is ready for the tutorial.

Important

These commands (along with many others) have to entered each time you start a new session so it can be tempting to put them into a login script. Resist this temptation and clean up your login script of other commands and environment settings as well; this is because different environment settings can interfere with each other and lead to crashes later on. Instead, put the relevant commands into a script that you execute at when you need it, rather than it happening automatically when you log in. You may also need to have different sessions for different tasks - for example the ATLAS software is incompatible with Rucio which is used for downloading files from the grid.

Setting up your own resources

Linux laptop or remote cluster

Any modern Linux distribution should work. The key requirement is to have set up CVMFS, since this gives remote (cached) access to all of the ATLAS (and general CERN) software. It also gives access to Linux images that are needed to run within containers, which is necessary unless you happen to be running Enterprise Linux 9, AlmaLinux 9 or similar. Instructions for setting up CVMFS are here; they require administrative rights so you may have to contact your system administrator if you are setting this up on a machine owned by your institute.

Once CVMFS is in place execute the following:

export ATLAS_LOCAL_ROOT_BASE=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase
alias setupATLAS='source ${ATLAS_LOCAL_ROOT_BASE}/user/atlasLocalSetup.sh'
setupATLAS -c el9
asetup Athena,main,latest

Apple Silicon Macs

If you have a Mac with "Apple Silicon" (e.g M1,2,3,4 etc) you can run the ATLAS software using Lima. Instructions are available here.

In brief, do:

limactl start https://gitlab.cern.ch/atlas-sit/containers/-/raw/master/Lima/almalinux9.yaml --name=alma9
limactl shell alma9
sudo cvmfs_config setup
cvmfs_config probe
alias setupATLAS='source ${ATLAS_LOCAL_ROOT_BASE}/user/atlasLocalSetup.sh'
setupAtlas
asetup Athena,main,latest

You should now be ready to run the tutorials!

Intel Macs

If you have an older Mac with an Intel processor it is probably easiest to run Linux in a Docker container. [Instructions are available here].

Windows laptops

Microsoft has prepared a helpful page explaining how to install Linux on a Windows machine. Please choose one of the methods described there (WSL preferred) and install AlmaLinux9. From there you can follow the instructions above for Linux.

Cloning and forking the Athena Git repository

Before coming to the tutorial, please ensure that you have made a local clone of Athena in your development area, and also fork the Athena repository in GitLab. This will allow you to develop and test software locally, and then push to the remote repository. Please follow the instruction here. There are two choices for the cloning: full and sparse. The full clone is the more "classical git" approach and is slightly simpler, but takes up more space. Unless your quota is severely constrained, use the full clone.

Access to distributed computing

Generally in this tutorial we will be using local interactive running only, but one of the exercises will require grid access. Please follow the links below (internal) to get grid access:

Minor modifications to the tutorial instructions

The tutorial instructions are all written to work out of the box on LXPLUS. If you are running on your own resources (which we hope you are) then you may have to make a few adjustments to the default instructions. Fortunately these are very minor and are explained below.

Defining setupATLAS

LXPLUS already defines the =setupATLAS= command. On other platforms you'll have to do this first. So if you aren't working on LXPLUS, at the start of each session you need to do:

export ATLAS_LOCAL_ROOT_BASE=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase
alias setupATLAS='source ${ATLAS_LOCAL_ROOT_BASE}/user/atlasLocalSetup.sh'
Then you can do setupATLAS (but see the next notes below).

Using an EL9 container

The ATLAS software is built on RedHat Enterprise Linux 9 (RHEL9) which is compatible with a family of distributions including AlmaLinux9 and RockyLinux9. Collectively we refer to these as "EL9". LXPLUS runs RHEL9 and so you can run the ATLAS software directly on the OS without a container (similarly, if you are running Lima you are already in an AlmaLinux9 container). For other Linux distributions you'll need to set up the ATLAS software in a container, as follows. If you don't run EL9 and see this in the instructions:

setupATLAS

do this instead:

setupATLAS -c el9

If you are storing input files on some volume that has a different mount point to the home directory you need to declare this when you create the container, e.g.

setupATLAS -c el9 -m /path/to/storage

Running the pre-tutorial tests

Warning

This is NOT recommended to do if you are using Lima on an Apple Silicon mac, e.g. a M1, M2, M3, M4

export ATLAS_LOCAL_ROOT_BASE=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase
alias setupATLAS='source ${ATLAS_LOCAL_ROOT_BASE}/user/atlasLocalSetup.sh'
diagnostics
setMeUp cern-jan2025

This will run a series of checks, reporting on the result for each one. Some of them require further input (e.g. password for the grid checks). If you have [OK] for all of the tests, you're ready to go! If you have any [FAILED] please contact the organisers via the channels mentioned in the mails relevant for the specific tutorial, or contact the software coordinators

Preparatory reading exercises

Before coming to the tutorial we'd like to ask you to review the Athena introduction, and then run and inspect the output of two simple Athena jobs, as well as looking at the code. The tutorial material and lectures will make more sense if you've already read the basic material and run some simple jobs.