# Getting setup ### Table of Contents * [ATLAS Software](/trtframework/getting-setup.md#atlas-software) * [Getting setup](/trtframework/getting-setup.md#getting-setup) * [Compiling the project](/trtframework/getting-setup.md#compiling-the-project) * [Config file and IO](/trtframework/getting-setup.md#config-file-and-io) * [Pushing to a GitLab repository](/trtframework/getting-setup.md#pushing-to-a-gitlab-repository) * [Handling the TRTFramework subrepo in your repo](/trtframework/getting-setup.md#handling-the-trtframework-subrepo-in-your-repo) * [Refreshing your existing working environment](/trtframework/getting-setup.md#refreshing-your-existing-working-environment) ## ATLAS Software If you're unfamiliar with ATLAS Software - [give this a read](/trtframework/atlas-software.md). 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](/trtframework/config.md). 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](https://gitlab.cern.ch/). 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](https://gitlab.cern.ch/atlas-trt-software). ### 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: ): ``` $ 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**](https://gitlab.cern.ch/atlas-trt-software/TRTFramework/tags)**.**) 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://atlastrt.gitbook.io/trtframework/getting-setup.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.