Author: P G Jones, p.g.jones@qmul.ac.uk
The SNO+ RAT code, tools and documentation can all be installed via the snoing tool. This tool aims to make the installation as simple and painless as possible. To start, however, you need a github account, as this is where all the snoplus code lives. To do so go to github to apply for an account, then ask for access to the snoplus organisation as explained in SNO+-doc-1462.
An ssh key for github is required to download all the snoing -dev packages. Follow the instructions at Github: Generating SSH Keys.
Once you have access to github you can download snoing via this command (make sure you have git installed):
git clone git@github.com:snoplus/snoing.git
Now you can run snoing to install the snoplus code. To do so, navigate to the snoing directory and type:
$ source env.sh
and then
$ ./snoing.py rat-dev
If you are missing any libraries on your system, then snoing will tell you. You will have to install these manually. If snoing completes without errors, then you are done. To run rat simply type
$ source install/env_rat-dev.sh
$ rat
Snoing takes care of software updating via the '-p' command e.g.
$ ./snoing.py -p rat-dev
updates rat-dev.
If snoing fails, then it will output "Snoing has failed, please consult the above error messages or the snoing.log file.". Above this line, snoing should output text explaining why it failed and will often give advice on how to solve the error. If this information is not sufficient to solve the problem, then email the snoing.log file to the MC group leader.
Snoing has the following options:
Usage: snoing.py [options] [package]
Options:
--version show program's version number and exit
-h, --help show this help message and exit
-c CACHE_PATH Cache path.
-i INSTALL_PATH Install path.
-v Verbose Install?
-l, --list List packages, without installing anything.
-a All packages?
-k, --clean Clean temporary files.
Optional Install modes:
-g, --graphical Graphical install?
-x Grid install (NO X11)?
Optional Actions:
Default snoing action is to install the specified package, which
defaults to rat-dev.
-q Query Package Status?
-r Remove the package?
-d Install dependencies only?
-p Progress/update the package?
Github authentication Options:
Supply a username or a github token, not both.
-u USERNAME Github username
-t TOKEN Github token
The traditional way to install RAT is to build the dependenices and RAT individually.
$ tar zxvf root_v5.34.36.source.tar.gz
$ cd root
$ ./configure --enable-minuit2 --enable-python --enable-mathmore
$ make # Use -jN for N parallel job
$ tar zxvf geant4.10.00.p02.tar.gz
$ mkdir geant4.10.00.p02-build
$ cd geant4.10.00.p02-build
$ cmake -DGEANT4_INSTALL_DATA=ON -DCMAKE_INSTALL_PREFIX=/PATH/TO/geant4.10.00.p02 /PATH/TO/geant4.10.00.p02
$ make
$ make install
$ tar zxvf scons-2.1.0.tar.gz
$ export RAT_SCONS = PATH/TO/scons-2.1.0
$ git clone git@github.com:snoplus/rat
$ cd rat
$ ./configure
$ source env.sh
Along the way we set a lot of environment variables, which must always be set to run RAT. To make this easier, create a script to do it:
# rat_env.sh
source /PATH/TO/root/bin/thisroot.sh
source /PATH/TO/geant4.10.00.p02/bin/geant4.sh
source /PATH/TO/RAT/env.sh
Then, you can just `source rat_env.sh` and RAT is ready to go.
Rat is git managed code; therefore, you must fetch and merge the code to update it manually before doing scons, i.e.
$ git fetch
$ git merge
$ scons
There a few options that can be passed to scons to disable or enable dependencies which are
Note: this method of installation hasn't been used by many people yet, please contact rebecca.lane@qmul.ac.uk with any feedback or issues
You can now make use of pre-built docker images containing RAT releases, in which ROOT, Geant4 and all the other RAT dependencies have already been installed for you. This may be useful if you have difficulty running RAT successfully on the operating system available to you (e.g. OSX), since it provides you with a container based on a Scientific Linux 6 environment in which to run RAT. General information on docker can be found in the docker instructions.
To have access to the docker images you must first create a docker hub account and request access be granted by emailing snoplusmc@snolab.ca with your docker hub username - for simplicity you could choose the same username as you use on GitHub. The docker images are hosted under the docker account rcl11/rat and can be seen on this page once access has been granted. Which docker image you are interested in depends on your purpose. For the majority of cases the analysts would want to make use of fixed releases. You need to make sure docker is installed on your system, and then you will need to login using your docker hub credentials as follows:
$ docker login
which will prompt you to provide your username and password, and then you can simply run the following commands to pull down the image you are interested in (e.g. for RAT tag 6.5.3):
$ docker pull rcl11/rat:6.5.3
$ docker run -i -t IMAGEID
The image ID can always be seen by running:
docker image ls
The "docker run" command will open a terminal window from which you can navigate inside the container as you would in a normal operating system. If you go to the /root directory (or type "cd") you'll find the location of the installed packages and the environment file you need to source to have access to RAT. Here you can run all the usual RAT code.
If you need to run RAT on some files which exist on your system then you can always mount a directory when you do the docker run command:
$ docker run -i -t -v /path/to/files:/root/files IMAGEID
This will make the contents of the "files" directory available inside the container. This directory can be written to from both your own local environment and from inside the container.
If you wish to use RAT for development purposes then there are a couple of different ways you can do this with the docker images. The image named "water_rat" will contain a clone with the current HEAD of the water_rat branch of RAT, equivalent to the "rat-dev" option with snoing above. The image containing the water_rat branch of RAT has been configured to automatically rebuild any time there is a new commit to water_rat branch. The text editors vim and emacs are installed in the image for use. You can also make use of the "dependencies" image which does not have RAT installed but does have all the dependencies. In this way you could have a clone of RAT on your own machine, and mount the directory containing it (using the "-v" option as above) when you run the docker image. This would allow you to make use of any IDEs or simple debug tools installed on your machine for development, whilst still compiling and running the code inside the container. Note that at minimum for development you will need to mount your .ssh directory using "-v" (or whatever directory you store your ssh key for GitHub in) in order for this to be available for pushing and pulling to git, e.g.:
$ docker run -i -t -v ~/.ssh:/root/.ssh IMAGEID
You can exit a container by simply typing "exit". The container will still exist, just in a stopped state. You can see your existing containers by running:
$ docker container ls -a
You can restart a stopped container by running:
$ docker start -i CONTAINERID
You could leave a container on your machine indefinitely and enter and exit it when you need to use it, or create a new container from the base image each time you need to do a specific RAT-task before deleting it afterwards. As more people try out this method of RAT installation we expect to update these instructions with some tips on a recommended workflow. In the meantime please do give feedback on any ways you find this useful to rebecca.lane@qmul.ac.uk.