Prerequisites - MinervaExpt/MINERvA-101-Cross-Section GitHub Wiki

In addition to the MAT and tutorial software (which we'll discuss how to download and build in the next step), you need some other basic software in order to do the tutorial. The main prerequisite is the ROOT Object-Oriented Toolkit. But the first thing you should do is to setup a working area and some directories that will help keep your files organized.

It is possible to execute this tutorial either on your own laptop or on a MINERvA computer at fermilab (a minervagpvm). Note that the instructions below are different for each of these cases, so be sure to follow the instructions relevant to your situation.

In any case, we have found significant speed improvements by way of having a local copy of the data. If you are participating in a hands-on tutorial, it is greatly recommended to have some files copied locally to whichever machine you are running the tutorial on. Your tutorial instructor should have sent around more detailed instructions with specifics driven by the adjustments needed for an in-person version itself.

Create a Working Area

The files that you'll download and create when working through the tutorial can be divided into three categories:

source code (usually .h, .cxx, .sh, and .py)
binaries and libraries (.so and compiled programs)
documents (.root and most .txt)

You are of course free to organize these files however you want, but we strongly recommend that you create separate directories for each of the above categories, as described below. We also recommend that you run your programs in your documents directory so that their output files end up in the right place automatically. You may find it convenient to have two terminals set up when you are working: one working in documents and another working on source code.

It is a good idea to keep these directories separate because:

Documents and binaries are specific to you and the computer you are working on. They shouldn't be in a version control system like git. If someone else wants them, they should usually make their own.
Fermilab has dedicated disk hardware for each of these categories. For example, /exp/minerva/app runs code faster than /pnfs but is more expensive, so you are limited in the amount of data you can store there.

Here's the directory structure you should create and use for this tutorial:

On a Laptop

CODE=~/app/MINERvA101 for source code and binaries
- ~/app/MINERvA101/opt for binaries
- Directories like ~/app/MINERvA101/MINERvA-101-Cross-Section will be created and populated with source code using git in the next step
DOCS=~/Documents/MINERvA101 for documents

On a MINERvA GPVM (Instructions untested on other GPVMs)

You might have to create /exp/minerva/app/users/$USER and/or /exp/minerva/data/users/$USER if you're new to MINERvA. Just use e.g. mkdir /exp/minerva/app/users/$USER if so and welcome to the team :). You should also create:

CODE=/exp/minerva/app/users/$USER/MINERvA101 for source code and binaries
- /exp/minerva/app/users/$USER/MINERvA101/opt for binaries
- Directories like /exp/minerva/app/users/$USER/MINERvA101/MINERvA-101-Cross-Section will be created populated with source code using git in the next step
DOCS=/exp/minerva/data/users/$USER/MINERvA101 for documents

Put this File in your Documents Directory

The packages we're about to install have to be told how to work together to read MINERvA's histogram format. Something called the dynamic linker does this when we compile a program, but scripts and interpreters need specialized help. So, we're going to create a ROOT configuration file specific to this MINERvA setup. Call it $DOCS/.rootlogon.C (~/.rootlogon.C ensures this is called every time you open ROOT):

{
  if( gSystem->Getenv("PLOTUTILSROOT") )
  {
    string newpath = string(gROOT->GetMacroPath()) + ":" + string("${PLOTUTILSROOT}/../bin" );
    gROOT->SetMacroPath( newpath.c_str() );
    gInterpreter->AddIncludePath( "${PLOTUTILSROOT}/../include" );
    gInterpreter->AddIncludePath( "${PLOTUTILSROOT}/../include/PlotUtils" );
    std::vector<std::string> packages = { "MAT", "MAT-MINERvA" };
    for(const std::string& package: packages)
    {
      gSystem->Load( gSystem->ExpandPathName(("$PLOTUTILSROOT/lib" + package + ".so").c_str()) );
    }
  }
}

Starting a file name with . makes it a "hidden" file on UNIX-like operating systems. ls won't show it, but ls -a will.

Your First ROOT Installation

The ROOT Object-Oriented Toolkit was written by physicists to speed up and simplify analysis of large data sets. It comes with its own libraries, a custom (binary) file format, and an interpreter that treats c++ like a scripting language. It even has "python bindings" that let us use its libraries from the python scripting language. It does some things really well and other things we just have to live with.

If you are working on a minervagpvm, ROOT is already installed, so you will not need to download or build it. If you are working on your own laptop, we recommend a tarball-based installation as your first approach (more instructions below). Building ROOT "from source" requires some knowledge of CMake and can get nasty quickly, but it allows you to enable optional features like reading detector geometry files that aren't available in some tarballs. Generally speaking, you should choose the newest version of root. The only reason not to get the newest ROOT version is that it might require a newer CMake or python version than what you have on your laptop. If that happens, especially on a Mac, just get a slightly older ROOT 6 tarball. The current version of this tutorial has been tested primarily with 6.28.12, but newer versions have worked without issue.

It is crucial that your ROOT installation has XRootD enabled as this is the bare minimum for accessing the data. Due to the running speed over XRootD streaming, it is highly recommended to copy the files locally to run as it can speed things up by factors approaching 10. Instructions should have been sent as part of any in-person tutorial. The Get Data page from the Open Data Product website has instructions if you have not been sent any, with the caveat that the files you copy should match one of the volumes of the 3 provided sizes in the playlist directory.

Copying the data currently requires the XRootD copy command xrdcp set up from what constitutes a full XRootD build. ROOT's pre-compiled binaries do not by default have XRootD built in. They are still XRootD-enabled to allow data access by streaming, but for copies of the data, more work is needed. For installation information for XRootD, visit their website. It can be built from source following their instructions. We have not tested this though.

We know for certain that Ubuntu versions older than 22 do not have XRootD available through apt, so please be warned that this may be the case as well for your operating system. We have noticed in testing that some package managers where you may get ROOT from (e.g. homebrew) will give you XRootD as well without any specific intervention. If you are building ROOT from source, you can pass the build option builtin_xrootd, to build XRootD also from source (requires network) during the ROOT build.

On a Linux Laptop

We're going to get (mostly) binaries for ROOT, so put it in ~/app/. I keep it separate because ROOT stays the same for any number of experiments and applications.

Follow the instructions for a tarball installation at https://root.cern/install/. When installing dependencies on Ubuntu 20.04, I had to leave out libssl-devel and a few others for which apt install gave me 404 errors. They seem to already be installed as part of a fresh OS install.
Please get a ROOT version compiled with c++14 or c++17 support if you can. I had to change one line in the tutorial CMakeLists.txt on Ubuntu 20 when I got a fairly recent ROOT tarball that was compiled with only c++11 support.
Set up ROOT in a new shell. You have to source /path/to/root/bin/thisroot.sh. Since I only ever work with 1 ROOT version on my laptop, I make this automatic whenever I open a terminal. To do that, put it as a new line in your ~/.bashrc.

On a MacBook

With homebrew:

brew install root
Install xcode to see the c++ standard libraries for things like std::vector.
You might have to brew update root too.

On one of Fermilab's GPVMs

Already done for you. I'll show you how to set up ROOT 6 on the GPVMs on the next page. If you ever need to do this on your own, research a website by Fermilab called SciSoft.

Every Time you Start Work

There are some commands that you will need to run every time you open a new terminal on your laptop or log in to a Fermilab GPVM. There's a script for this under the bash command line, ~/.bashrc on most laptops and ~/.bash_profile on the GPVMs, that you can put these commands into. Just remember that you might have to edit it one day if/when you work on another Fermilab experiment.

source $CODE/root/opt/bin/thisroot.sh #Set up ROOT.  On MacOS installed via Homebrew, might be /usr/local/bin/root/thisroot.sh instead/. Don't do this on the gpvm's.

Note that if you are working on a minervagpvm, you have not yet setup root, so the third line above is not going to workd