(installing)= # Installing ROOT on your own computer Either you have no choice, or you've decided to ignore my {ref}`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 {ref}`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](https://docs.conda.io/projects/continuumio-conda/en/latest/user-guide/install/index.html) to install Miniconda[^f105]. Once you've installed Anaconda, you'll want to include [conda-forge](https://conda-forge.org/) 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](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) 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 {ref}`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](https://twiki.nevis.columbia.edu/twiki/bin/view/Main/Conda). The [conda page on managing environments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) 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](https://www.macports.org/) has both ROOT and Jupyter. In RHEL-derived Linux systems, the [EPEL repository](https://fedoraproject.org/wiki/EPEL) 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. :::{figure-md} shouldnt_be_hard-fig :class: align-center xkcd shouldnt_be_hard by Randall Munroe ::: ## Docker While [Anaconda](https://docs.anaconda.com/anaconda/) is an environment-level container, Docker (and Singularity below) are OS-level containers.[^f106] [Docker](https://www.docker.com/) 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 {ref}`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](https://www.docker.com/products/docker-desktop); there's a [different procedure](https://runnable.com/docker/install-docker-on-linux) 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](https://pip.pypa.io/en/stable/user_guide/)) to install new Python packages or [yum](http://yum.baseurl.org/wiki/YumCommands.html)) to install new Linux packages.[^f107] 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](https://docs.docker.com/engine/reference/commandline/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](https://docs.docker.com/engine/reference/commandline/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. :::{figure-md} containers-fig :class: align-center xkcd containers by Randall Munroe ::: ## Singularity If you don't have admin access to your local computer, or you simply prefer it, you can use [Singularity](https://sylabs.io/guides/3.5/user-guide/) instead. You still need admin access to install Singularity, or a willing sysadmin to do it for you.[^f108] 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 {ref}`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: - [Python](https://wiki.python.org/moin/BeginnersGuide/Download) (if it's not already installed on your system) - [ROOT](https://root.cern/install/) - [Jupyter](https://jupyter.readthedocs.io/en/latest/install.html) 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](https://github.com/wgseligman/docker-jupyter-pyroot/blob/master/Dockerfile) I used to create the [wgseligman/jupyter-pyroot](https://github.com/wgseligman/docker-jupyter-pyroot) container may provide a clue for how to create your own installation. :::{figure-md} fixing_problems-fig :class: align-center xkcd fixing_problems by Randall Munroe ::: [^f105]: For this tutorial, the full Anaconda set of packages is not necessary. Note that all the Nevis particle-physics systems already have conda installed. [^f106]: In contrast to emulators like VMware, which are machine-level containers. [^f107]: If you install something of general interest, let me know. I may add it to the main jupyter-pyroot container. [^f108]: Singularity is already installed on all the systems in the Nevis particle-physics Linux cluster.