Getting setup
Last updated
Last updated
If you're unfamiliar with ATLAS Software - . 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).
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:
Now let's setup an ATLAS Analysis Release
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:
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:
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.
Since we have some code, let's compile it.
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.
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.
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.
Now we can actually run the algorithm (we always define an output directory with the -o flag):
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!
One of the things that python script did was make your project a git repository. Let's make your first commit.
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.
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:
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):
When you exit your shell and come back, you'll need to re-setup your environment. Do that with:
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.
There's a dedicated documentation page which describes all of the config parameters (and how to add custom ones). That's . For now we'll continue with the tutorial while using the default one, we'll talk about making some changes in a later section.
Now we want to push them to GitLab. Sign into . 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 .
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: ):
(Remember, you'll always be able to find a list of TRTFramework tags .)