Prerequisites

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.

Create a Working Area

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

1. source code (usually .h, .cxx, .sh, and .py)
2. binaries and libraries (.so and compiled programs)
3. 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, /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 Fermilab GPVM

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

• CODE=/minerva/app/users/$USER/MINERvA101 for source code and binaries
  • /minerva/app/users/$USER/MINERvA101/opt for binaries
  • Directories like /minerva/app/users/$USER/MINERvA101/MINERvA-101-Cross-Section will be created populated with source code using git in the next step
• DOCS=/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:

{
  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 downlaod 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.

On a Linux Laptop

We're going to get (mostly) binaries for ROOT, so put it in ~/app/. I keep it separate because one day, you're going to be such an awesome physicist that you'll work on MINERvA and DUNE or something. ROOT stays the same for both.

1. 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.
2. 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.
3. 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.
4. To keep your PlotUtils code up to date, you'll need to install kerberos too for now. On Ubuntu, you want the package krb5-user for MIT kerberos and not Heimdall Kerberos. Then, you'll need to update your /etc/krb5.conf to match Fermilab's standards.

On a MacBook

With homebrew:

1. brew install root
2. Install xcode to see the c++ standard libraries for things like std::vector
3. You might have to brew update root too
4. To keep your PlotUtils code up to date, you'll need to install kerberos too for now. You need MIT kerberos and not Heimdall Kerberos to talk to Fermilab's code repositories. Then, you'll need to update your /etc/krb5.conf to match Fermilab's standards.

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.

export CVSROOT=minervacvs@cdcvs.fnal.gov:/cvs/mnvsoft #All CVS version control packages come from MINERvA via Fermilab
kinit #Use your Fermilab computing account.  Don't do this on GPVMs.  There's a way around this if you can't do it on your personal computer.
source $CODE/root/opt/bin/thisroot.sh #Set up ROOT.  On MacOS installed via Homebrew, might be /usr/local/bin/root/thisroot.sh instead/. Also 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

Next: Installation