Getting setup

Table of Contents

• ATLAS Software

• Getting setup

• Compiling the project

• Config file and IO

• Pushing to a GitLab repository

  • Handling the TRTFramework subrepo in your repo

• Refreshing your existing working environment

ATLAS Software

If you're unfamiliar with ATLAS Software - give this a read. All TRTFramework documentation is going to be related to ATLAS "Analysis Releases." Not Athena! If these sentences didn't make sense to you, click that link.

I'm also going to assume that you're working on lxplus or something similar. (Something with ATLAS CVMFS directories mounted... where you can run setupATLAS).

Getting setup

First, let's define a few things:

• Working Area: Pretty self explanatory - where you'll be doing your work; in this area we will store code, build files, and launch jobs. I'm going to call the path /path/to/workarea

• Source Area: This is where code you develop is going to live. It will be a git repository and will be the name of your project. For the purpose of this tutorial I'm going to call mine AnaProject. You should call yours something related to your project! I'm going to call the path /path/to/workarea/AnaProject.

• Build Area: This is where we'll compile code, you won't actually edit any files here, you'll just be using cmake to build and compile here. I'm going to call the path /path/to/workarea/build.

• Run Area: This is where we'll execute our code (run our algorithm). I'm going to call the path /path/to/workarea/run.

Let's get to it, create a working area:

$ cd /path/to/workarea
$ mkdir -p /path/to/workarea/run
$ mkdir -p /path/to/workarea/build

Now let's setup an ATLAS Analysis Release

$ cd build
$ setupATLAS # if you haven't done this already
$ asetup 21.2.20,AnalysisBase
$ lsetup git

You now have an analysis environment using the 21.2.20 release (the latest release at the time of writing this). We're now going to generate a skeleton project which will take advantage of the TRTFramework package:

$ cd ../
$ curl https://gitlab.cern.ch/atlas-trt-software/TRTFramework/raw/v2.X-branch/scripts/GenerateProject.py | python - AnaProject

You only need to complete that step once to create a new project.

Remember, I'm calling my project AnaProject -- you should call yours something related to your project!

You should now have the following structure in /path/to/workarea:

.
├── AnaProject
│   ├── AnaProjectLooper
│   ├── CMakeLists.txt
│   ├── README.md
│   └── TRTFramework
├── build
└── run

The script you just downloaded with curl and ran with Python created a skeleton project and checked out TRTFramework as a git submodule. This is a git repository within a git repository. Your project is the top level git repository. TRTFramework is a package within it. We also created a package called AnaProjectLooper. This is going to be your package which inherits from TRTFramework. The reason why we call it [ProjectName]Looper is because the package is going to be home to a "loop algorithm."

The script set you up to have TRTFramework from the v2.X-branch branch. We'll talk about branches and tags a bit later.

Right now the project does nothing. It's a skeleton. We're going to develop code in the new package to actually do something.

Compiling the project

Since we have some code, let's compile it.

$ cd /path/to/workarea/build
$ cmake ../AnaProject
$ make -j4
$ source $AnalysisBase_PLATFORM/setup.sh

The cmake command generates the files required for the build, and then we compile with make. CMake also generates a setup script that we source (this sets up the necessary environment variables to use our now compiled library and executable). If you are using a local cluster and not lxplus, it's possible that the $AnalysisBase_PLATFORM environment variable may not be set properly. In that case, look in your build directory and find a folder that starts with x86_64..., your setup script should be in there.

You should now have a new executable at your disposal. Mine is called runAnaProjectLooperAlg. If you run it, you'll get a message telling you that you're missing some command line arguments, specifically a config file. Let's talk about the config file.

Config file and IO

Everytime you use TRTFramework, you'll be required to use a config file. We supply a default one: TRTFramework/data/default.cfg. Let's use it.

$ cd /path/to/workarea/run
$ cp ../AnaProject/TRTFramework/data/default.cfg .

There's a dedicated documentation page which describes all of the config parameters (and how to add custom ones). That's here. For now we'll continue with the tutorial while using the default one, we'll talk about making some changes in a later section.

The whole purpose of the algorithm is to process some DAODs. Let's talk input/output (IO). There are two ways to process DAODs with TRTFramework: either a plain text file with a list of DAOD files, or a grid dataset. For this tutorial, we have some sample files saved in EOS for easy use with the plain text file input. We'll talk about the grid later.

$ cp ../AnaProject/TRTFramework/data/sample_list.txt .

Now we can actually run the algorithm (we always define an output directory with the -o flag):

$ runAnaProjectLooperAlg -c default.cfg -i sample_list.txt -o job_output

Congrats! You've just run your first TRTFramework based algorithm. The output files are in the new directory job_output. Unfortunately, the algorithm does nothing... we will change that soon!

Pushing to a GitLab repository

One of the things that python script did was make your project a git repository. Let's make your first commit.

$ cd /path/to/workarea/AnaProject
$ git status # see all the files
$ git add . # stage them for commiting
$ git commit -m "first gimmit" # make the commit.

Now we want to push them to GitLab. Sign into CERN's GitLab. Create a new personal repository with the name of your project. Then follow the instructions for pushing an existing repository. Once you've created a functional project, ask to have it moved under the atlas-trt-software project page here.

Handling the TRTFramework subrepo in your repo

TRTFramework exists as a submodule in your repository. Think of it as just a single file in your repository, but when you cd into it, it is an isolated git repository. If you checkout a branch in the TRTFramework git repo, then your git repo will see the TRTFramework "file" as changed, because the repo is now in a different state.

The branch v2.X-branch is where your TRTFramework subrepo is set, this is always going to be the latest supported version of the code for analyzing release 21 DAOD's.

Let's say you want to check out a specific tag of TRTFramework (tag v2.0 for example. You can always find a list of tags here: https://gitlab.cern.ch/atlas-trt-software/TRTFramework/tags):

$ cd /path/to/workarea/AnaProject/TRTFramework
$ git fetch origin           ## communicate with the remote gitlab repo to get updates about the repo
$ git checkout -b v2.0 v2.0  ## create local "v2.0" branch that is the same as the remote "v2.0" tag

Now if you run git status in your repo it will tell you that TRTFramework has changed. You can make your submodule clone of TRTFramework line up with the v2.0 branch by just treating TRTFramework like a changed file:

$ cd /path/to/workarea/AnaProject
$ git add TRTFramework
$ git commit -m "sync TRTFramework with tag v2.0"
$ git push origin master

(Remember, you'll always be able to find a list of TRTFramework tags here.)

All v2.X tags will be created from snapshots of the v2.X-branch branch.

If you want to just always use the v2.X-branch (which would be using the "cutting edge" version), you can just grab those updates via (if your local TRTFramework is still in v2.X-branch):

$ cd /path/to/workarea/AnaProject/TRTFramework
$ git fetch origin
$ git checkout 2.X-branch
$ git pull origin v2.X-branch
$ cd ..
$ git add TRTFramework
$ git commit -m "get latest TRTFramework v2"
$ git push origin master

Refreshing your existing working environment

When you exit your shell and come back, you'll need to re-setup your environment. Do that with:

$ cd /path/to/workarea
$ cd build
$ setupATLAS
$ asetup 21.2.20,AnalysisBase
$ lsetup git
$ cmake ../AnaProject # not necessarily needed but good for completion
$ make                # not necessarily needed but good for completion
$ source $AnalysisBase_PLATFORM/setup.sh

Moving on

Alright, now that we have a project that compiles and runs, let's actually start making your algorithm do something. At this point, I'm going to expect that you have some basic knowledge of ROOT. On to the next phase, algorithm development.