Installing ROOT on your own computer

Either you have no choice, or you’ve decided to ignore my warning. Here are various methods to install ROOT+Jupyter on your own computer. They are listed in ascending order of complexity.

Anaconda

Anaconda is a software manager that allows you download and execute packages in your home directory.

If you use the Nevis Linux cluster, then you should consider using environment modules over Anaconda. But if you’re on a different system, or the Nevis environment modules don’t offer the package or version you’re looking for, Anaconda is a better choice. You can install Anaconda in your home directory so admin access is not necessary. Simply follow the web site directions to install Miniconda1.

Once you’ve installed Anaconda, you’ll want to include conda-forge for packages such as ROOT. The following commands set it up:

conda config --add channels conda-forge
conda config --set channel_priority strict

At this point, you’ll probably have log off then log in to your computer again to give conda a chance to set up your shell.

To install Jupyter/ROOT, with sufficient features for most of this tutorial:

conda create --name jupyter-pyroot jupyter python root

Note that the name jupyter-pyroot is arbitrary; you can use any name for the conda environment that you wish.

If you continue to work with Jupyter or ROOT after this tutorial, there are standard packages that you’ll probably want to include:

conda install --name jupyter-pyroot jupyterlab numpy scipy matplotlib

Your working group may use additional packages. For example, the VERITAS group at Nevis might want to use (in addition to the above):

conda install --name jupyter-pyroot astropy gammapy

You only have to go through the above steps once to define an environment (e.g., jupyter-pyroot). Afterwards, once per login session, it’s necessary to activate it:

conda activate jupyter-pyroot

Once activated, you should be able to run ROOT by simply typing:

root

You can run jupyter with:

jupyter notebook

Warning

  • Conda takes a long time to run. Be patient. I’ve seen some conda environments take hours to install.

  • A conda environment can take up a lot of disk space, since it not only installs the packages you list, but any other packages that they depend on. On my desktop computer, the minimal Jupyter/ROOT container described above takes up 3G. This may not seem like much, but summer students at Nevis have a disk quota of 10G.

    It’s possible to run into disk-space problems, especially if you’re sharing disk space with other users, if you add more packages to your environment, or you define multiple environments for different projects.

  • Anaconda changes your shell’s execution environment. It may be incompatible with other environment setups (such as MicroBooNE’s LArSoft, ATLAS’ Athena, or Nevis’ module load command).

  • Your shell’s prompt will be changed by conda. Even when you’re not using conda, the text (base) will appear at the beginning of the prompt. If this doesn’t bother you, then ignore it. If it does, you can try:

    conda config --set auto_activate_base false
    

    You’ll have to log off then log in again to see the change. If you don’t want conda to alter your prompt even when you’re using an environment, this command will suppress conda’s prompt changes:

    conda config --set changeps1 False
    

Tip

One of the most common questions I’m asked is how to relocate a conda environment to some other location than one’s home directory:

  • As noted above, conda environments take up a lot of disk space. Most research groups have additional disk storage that’s not part of a home directory; you can read about how the Nevis particle-physics groups handle their storage in Shared filesystems.

  • Many research groups want to share their conda environments, to make sure that everyone is using the same versions.

For tips on managing disk space for your conda environments, see the Nevis conda wiki page. The conda page on managing environments is also helpful.

Other packaged distributions

There are other packaging systems than Anaconda; I only emphasized that one because it’s available on Mac OS X, Windows, and Linux. But if you’re already using a package system, ROOT may be a part of it.

For example, MacPorts has both ROOT and Jupyter. In RHEL-derived Linux systems, the EPEL repository has also has both ROOT and Jupyter.

The difficulty with some of these packaged distributions is that the ROOT+Jupyter integration might need some work on your part.

xkcd shouldnt_be_hard

Figure 42: https://xkcd.com/1349/ by Randall Munroe

Docker

While Anaconda is an environment-level container, Docker (and Singularity below) are OS-level containers.2 Docker is probably the best method of running Jupyter+pyroot without having to worry about issues like package compilation, though you won’t be able to use it to go through The Basics. Its disadvantage is that it requires administrative access to the host computer system (e.g., your laptop), both to install Docker and to run the Docker container.

The first step is to install Docker. For Mac and Windows systems, use Docker Desktop; there’s a different procedure needed for Linux systems.

Once Docker is installed and running, you’ll be able to download and run a Docker container:

sudo docker run -p 8080:8080 -v $PWD:/work wgseligman/jupyter-pyroot

(Windows users will probably need to use %CD% instead of $PWD.)

The first time you run this command, it will download a ~2.5GB container. Give it time.

Finally, you’ll see some output. Look at that output carefully, as it will tell you how to access Jupyter via a web browser. For example, assume the output contains something like this:

To access the notebook, open this file in a browser:
file:///root/.local/share/jupyter/runtime/nbserver-1-open.html
Or copy and paste one of these URLs:
http://649d0c4b4dc1:8080/?token=97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c
or
http://127.0.0.1:8080/?token=97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c

Remember, your complicated token won’t be 97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c. That was just the value returned by Jupyter at the time I created this example.

Start up a web browser and visit (in this example):
http://127.0.0.1:8080/?token=97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c

You’ll see the standard Jupyter home page.

That will get you started. The next few sub-sections are for refining your use of Docker.

Changing the port

Consider the command:

sudo docker run -p 8080:8080 -v $PWD:/work wgseligman/jupyter-pyroot

That first 8080 is the port to use on your local computer. If you want to use a different port on your computer (for example, you’re already using port 8080 for something else), change that first 8080 to a different port. Note that if you change the port, you’ll also have to change the port in the URL in the output; e.g.,

sudo docker run -p 7000:8080 -v $PWD:/work wgseligman/jupyter-pyroot

means you’ll have to change:

http://127.0.0.1:8080/?token=97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c

to:

http://127.0.0.1:7000/?token=97d7242fc79734f1429bc425c627ccc4f586675c01ecdd9c

Changing the directory

Again, consider:

sudo docker run -p 8080:8080 -v $PWD:/work wgseligman/jupyter-pyroot

That $PWD (%CD% in Windows) just means “the current directory.” The execution environment within the container uses /work for its files; the -v option in the command means “map /work to the current directory in the terminal.” If you’d like to use a different directory on your computer as the work directory in the Docker container, substitute that directory for $PWD. For example:

sudo docker run -p 8080:8080 -v ~jsmith/root-class:/work wgseligman/jupyter-pyroot

Changing the container

You can use New -> Terminal within Jupyter to get a shell. Within that shell, you can modify anything within the container you want; for example, you can use pip3) to install new Python packages or yum) to install new Linux packages.3

However, any changes you make to the Docker container won’t be automatically saved when you quit the container. When you next start the container, it will start “fresh.” If you want to save your changes, you’ll have to commit.) them.

For example, assume that you’ve made some changes to your copy of the jupyter-pyroot container. Look up the ID of the container as assigned by your local docker process:

sudo docker container ls
CONTAINER ID IMAGE COMMAND [...]
1105371318e8 wgseligman/jupyter-pyroot "jupyter notebook ..." [...]

Your output will be different; I’ve omitted most of the columns, and you’ll have a different CONTAINER ID. Commit a revised container using your own image name:

sudo docker commit 1105371318e8 $USER/jupyter-pyroot

You’ll can see your new image with the docker images command. For example, if $USER is “jsmith”:

sudo docker images
REPOSITORY TAG IMAGE ID [...]
jsmith/jupyter-pyroot latest 97ca601cbf9c [...]
docker.io/wgseligman/jupyter-pyroot latest 16c3bbdc8144 [...]

From that point forward, you’ll probably want to run your new container with your changes:

sudo docker run -p 8080:8080 -v $PWD:/work jsmith/jupyter-pyroot

Docker container notes

I prepared the container wgseligman/jupyter-pyroot to be similar to the environment of the notebook server; for example, it runs the same version of the OS and of ROOT (as of Dec-2021, that’s CentOS 7 and ROOT 6.24.06).

A little bit web searching will show there are other ROOT containers available. For example:

sudo docker run -p 3000:8080 pedwink/pyroot-notebook

That particular container uses Fedora 28 and ROOT 6.14, and it also offers Python 2 versions of its notebook kernels (wgseligman/jupyter-pyroot only offers Python 3).

So, if you can’t find the feature you want in wgseligman/jupyter-pyroot, hunt around a bit. It’s probably out there.

xkcd containers

Figure 43: https://xkcd.com/1988/ by Randall Munroe

Singularity

If you don’t have admin access to your local computer, or you simply prefer it, you can use Singularity instead. You still need admin access to install Singularity, or a willing sysadmin to do it for you.4

To download the container and convert it to Singularity’s .sif format:

singularity pull docker://wgseligman/jupyter-pyroot

After some processing, you’ll have the image file jupyter-pyroot_latest.sif. Then you can run Singularity on that container:

singularity run --bind=$PWD:/work jupyter-pyroot_latest.sif

Note that while you can change the mapping of the /work directory within the container (see the Docker instructions above), you can’t change Jupyter’s binding to port 8080. This might be a problem if you’re running on a shared computer system and more than one user wants to run this container at the same time.

The hard way: compiling ROOT and Jupyter from scratch

I repeat my advice: Don’t.

Obviously, it’s possible to install these packages from scratch; I do it all the time. But it can take a while to learn how to do it. You’d learn a lot about UNIX, but you’ll be learning neither ROOT nor physics. Don’t expect me to break from teaching other students about ROOT to teach you about your C++ compiler and the location of your Python distribution in your directory hierarchy.

Now that you have been warned, here are the places to start:

Please keep the following in mind:

  • These are not applications that you can double-click to automatically install. The process requires some knowledge of the command shell.

  • Read the installation documentation for each package. Use some thought and initiative. If you aren’t familiar with UNIX shells before you started this process, you will be once you finish!

  • The dockerfile I used to create the wgseligman/jupyter-pyroot container may provide a clue for how to create your own installation.

xkcd fixing_problems

Figure 44: https://xkcd.com/1739/ by Randall Munroe


1

For this tutorial, the full Anaconda set of packages is not necessary. Note that all the Nevis particle-physics systems already have conda installed.

2

In contrast to emulators like VMware, which are machine-level containers.

3

If you install something of general interest, let me know. I may add it to the main jupyter-pyroot container.

4

Singularity is already installed on all the systems in the Nevis particle-physics Linux cluster.